Docs

Docs

The docs site for Parro Nexus (the one you are looking at now) is maintained from within the Parro nexus repo. This site renders markdown files using Hugo with the Docsy template.

When you make changes to the markdown, or add new documentation it will auto update the site using a Jenkins job

The Jenkinsfile for this job contains the following steps:

Validate

dockerfile.validate {}

This will validate the Dockerfile locates in the docs dir docs/Dockerfile

Build the site

Since hugo generates all the static html we need to run it against the source of this repository. There is no default jenkins step for hugo so we run the commands inside a docker image from hugo. Since jenkins will mount the current workspace dir inside the container this will have the same effect as running hugo inside the docs directory

docker.image("klakegg/hugo:ext").inside("--entrypoint=\"\"") {
    sh("""
        git submodule update --init --recursive themes/docsy 
        hugo
    """)
}

Build docker image

def img = dockerfile.build {
    stage = "Build image"
    name = "parro-connect/docs"
}

Build the docker container with the generated static html pages

Publish the image

dockerfile.publish {
    stage = "Publish image"
    image = img
    distribute = false
    tags = ["${tag}"]
}

Publish the image to the artifactory

Deploy

stage("Deploy"){
    if(branchName == "main"){
        build   job: "geon/Microservices/deploy_development",
                wait: false,
                propagate: true,
                parameters: [
                    string(name: 'service_name', value: "docs"),
                    string(name: 'new_version', value: tag),
                ]
    }else{
        jenkinsHelper.markStageAsSkipped("Deploy")
    }
}

All commits on the main branch should be published. This is done by a separate job geon/Microservices/deploy_development

Running the docs local

There are 2 ways to run the docs local:

• Install hugo
• Run it in a container

For both options there is a script in the docs dir:

• start_docs.sh -> will start a docker container
• start_docs_local_hugo.sh -> will start hugo with the correct startup parameters

Both scripts will start hugo in a watch mode which will show updates as you type. The local site is served at http://localhost:1313