Building and Deploying

Managing and Publishing versions

Versioning is handled through mike. The way it works is it creates commits on the gh-pages branch, rendering the current docs in a subdirectory named like the release name.

When pushing tags, the CI/CD system will invoke mike and push the new commit to gh-pages to publish the tag as a new release.

Local Development

For local development, you need to set up PYTHONPATH in order for mkdocs to find the custom extensions. For convenience, the script tools/mike can be used to invoke mike commands with the correct environment.

To create a new version, you can use:

tools/mike deploy 1.2

This will create a new commit on gh-pages and publish the docs under 1.2, note that you don't need to commit the changes in your working branch in order to do this.

Deploying the same version will simply overwrite existing contents.

To locally view the specs with versioning enabled, use

tools/mike serve

Which will display the docs based on the contents of the gh-pages branch.

If you want to publish version changes, remember to fetch gh-pages before making any changes.

Aliases

mike supports adding version aliases, we'll mostly use the latest alias to point to the current published version of the specs.

You can add / update an alias like so:

tools/mike alias -u 1.2 latest

The workflow Tag Latest can be triggered on a tag to mark it as the latest version.