This documentation describes a release under development. Documentation for the latest release, 3.6.2, can be found here.

Building Mitto Documentation

Two types of Mitto documentation can be built: single-version and multi-version. Single-version is the original documentation framework that supports only a single body of documentation – that of the currently checked-out branch. Multi-version is the newest framework that supports publishing multiple versions of documentation (i.e., a version for each Mitto release).

Generally, one wants to build multi-version documentation when publishing documentation for a Mitto release. Single-version documentation is useful when in the process of developing documentation for a release as it is much faster to produce.

Warning

Multi-version documentation can only be built using Mitto 2.9.0 or later. However, multi-version documentation created with Mitto 2.9.0 or later can include documentation for any Mitto version for which documentation exists (e.g., 2.5.1, 2.7.5, etc.).

Public vs. Private

There is also the notion of public and private documentation. Public documentation is published to https://zuar.com/api/mitto and is accessible by anyone. Private documentation is published elsewhere and is accessible only by whitelisted IP addresses.

The PVT environment variable controls which documentation is being worked with by commands. If PVT is not set or if it is set to something other than y, public documentation is being worked with. If PVT is y, then private documentation is being worked with.

Important

When working with documentation locally, only one flavor of documentation can be built and viewed at a time. This is because the generated HTML is placed in the same directory, regardless.

Thus, when publishing documentation for a release, one generally follows this pattern:

  • build, view, publish public documentation

  • build, view, publish private documentation

It is not possible to build both types and then publish both types.

Documentation Environment

Before documentation can be built, the environment must be setup.

cd $MITTO_HOME
. pyenv/bin/activate
cd mitto/docs
make pyenv

This will install Sphinx and related packages necessary to build documentation.

Schemas and Release Notes

Before building the documentation, determine if the JSON schemas and release notes need to be updated.

  1. JSON schema documents.

    cd docs
MITTO_DATA=/var/mitto make schemas         # public schemas
MITTO_DATA=/var/mitto make PVT=y schemas   # private schemas

    This will create JSON schema documentation locally in:

    docs/src/schemas     # public documentation
docs/srcp/schemas    # private documentation

    Setting MITTO_DATA, as shown above, is usually necessary because it is likely to have a different, non-default, value on a developer machine. The value above is the Mitto production default. The value of MITTO_DATA is embedded in some documentation that is generated.

    Commit any new/changed schema documentation to version control.

  2. Release notes. For example, to create release notes for release 2.8.10:

    cd docs
MITTO_REL=2.8.10 make release_notes

    This will create docs/src/release_notes/2.8.10.md.

    Following this, manually update docs/src/release_notes/index.md to point to the newly created release notes.

    Important

    The MITTO_REL value must exactly match the release number used in Jira, as it is used to query Jira ticket information when building release notes.

  3. If building multi-version documentation, any changes to documentation source resulting from the above must be checked-in to the repository for the changes to appear in the generated documentation.

Single-version Documentation

With the advent of multi-version documentation, single-version documentation is really of use only when actively developing documentation for a release. Working with single-version documentation offers the following advantages:

  • Documentation is built only for the currently checked-out branch This eliminates the overhead of building documentation for multiple releases.

  • Documentation is generated from the source files present in the current branch – it is not necessary to check-in changes prior to building documentation. This is especially convenient when one is actively developing documentation.

Other differences:

  • The generated single-version is placed directly under docs/build/html; it is not placed in its own subdirectory.

  • Version information and selection is not present in the sidebar.

Build the Documentation

cd docs
make clean
make version         # public documentation
PVT=y make version   # private documentation

View the Local Documentation.

cd docs
make serve           # public documentation
PVT=y make serve     # private documentation

The, in your browser, navigate to http://localhost:8000.

Publish the Documentation

Single-version documentation can be published in exactly the same way as multi-version. However, doing so will wipe-out existing multi-version documentation. It’s unlikely that single-version documentation should be published.

Multi-Version Documentation

When multiple versions of documentation are built, they are built into docs/build/html. Each version is contained in its own subdirectory. E.g.:

$ tree -L 1 docs/build/html
docs/build/html
├── 2.8.6
├── 2.8.7
├── 2.8.8
├── 2.8.9
├── 2.8.10
└── master

A special index.html is built an placed in docs/build/html; it automatically redirects browsers to the “current” version of the documentation. Links in the sidebar of each page display the version currently being viewed and allow the user to switch documentation versions.

Creation of multi-version documentation is controlled by environment variables. They can be set once or they can be provided on the command line each time make is run.

The first two control the documentation that is built; they specify the git branches and tags of interest. Roughly, they define the “releases” that documentation will be built for.

MITTO_TAGS

A string containing a regular expression matching the tags for which to generate documentation. E.g.: MITTO_TAGS="2.8.[89]|2.8.1[012]"

MITTO_BRANCHES

A string containing a regular expression matching the branches for which to generate documentation. E.g.: MITTO_BRANCHES="master"

The remaining variables fine-tune the documentation.

MITTO_LATEST

A string defining the most recently released version of Mitto. This is used for the latest links in the generated HTML. It must be a valid tag or branch in git. E.g.: MITTO_LATEST="2.8.12"

MITTO_REL

A string containing the Jira release number for which to create release notes. This is only used when make release_notes is used to build release notes. E.g.: MITTO_REL="2.9.0"

MITTO_RELEASED

A string containing a regular expression matching the tags or branches which have been released. This is matched against the full git refname returned by git for-each-ref --format "%(refname)". E.g.: MITTO_RELEASED='^refs/tags/2.8.(8|9|1[0-2])$'

This is used to classify a “release” as either “released” or in “development”.

Important

When building multi-version documentation the sphinx-multiversion command is used instead of sphinx-build. For sphinx-multiversion to work properly, all documentation must be checked-in to the repository. Changes made locally, but not checked-in to the current branch, will not appear in the generated documentation.

Define and Confirm What will be Built

For this example, we will update our environment with the specifications of the documents to generate, then we’ll confirm the exact versions that will be built:

export MITTO_BRANCHES="(2.9.x|master)$"
export MITTO_TAGS="2.8.(8|9|1[0-2])"
export MITTO_LATEST="2.8.12"
export MITTO_REL="2.9.0"
export MITTO_RELEASED='^refs/tags/2.8.(8|9|1[0-2])$'
make versions-show
Documentation will be built for the following versions:
[
    "2.8.10",
    "2.8.11",
    "2.8.12",
    "2.8.8",
    "2.8.9",
    "2.9.x",
    "master"
]

HINT: It may be easisest to start with the values used in the most recent build of documentation and modifying them.

Let’s review the values used above:

  • MITTO_BRANCHES / MITTO_TAGS – together these define the versions of documentation that will be created. Nothing else controls the selection of documentation that is built.

  • MITTO_LATEST – 2.8.12 is the most recent version of Mitto that has been released.

  • MITTO_REL – development on 2.9.0 will be complete within a week or two. This value is used when querying Jira for tickets to include in the release notes.

  • Because we are nearing the release of 2.9.0, a 2.9.x branch has been created to allow ongoing new feature development to continue on master.

  • MITTO_RELEASED – this regex controls classifications of a version. Because they do not match the regex, the 2.9.x and master branches will both be classified as development. All other versions will be classified as released.

Build the Documentation

cd docs
make clean
make release_notes
if needed, update generated release notes manually
$ git add <release_notes.md>
$ git commit -m 'NO-TICKET: <x.y.z> release notes'
$ git tag -m <x.y.z> <x.y.z>
$ git push
make versions

make versions generates a complete set of documentation for each release. Documentation for each version is placed in its own directory under docs/build/html.

Important

The generated HTML (i.e., the contents of mitto/docs/build) is never checked-in to the repo; only the source documents are controlled.

View the Local Documentation.

cd docs
make serve

In your browser, navigate to http://localhost:8000.

Publish the Documentation

If the local documentation looks good, publish it to zuar.com.

cd docs
make publish

Post-Release Documentation Updates

Want to update docs for a release without performing all the other release related tasks? Here’s how.

Author the Changes

Assume that 2.9.4 has been released and that documentation changes need to be made and published. 2.9.4 is a tag on the 2.9.x branch.

On the tip of the 2.9.x branch, create a new branch and make the desired documentation changes and commit them.

Build the documentation and view it locally:

# 'make version` instead of 'make versions' saves time
make version
make serve

Once it looks good, commit the changes, push to github, create a PR, merge the PR into 2.9.x, then do a git pull.

Build and Publish the Documentation

We’ll adopt the convention that documentation-only updates will be tagged by appending a _n to the previous release tag, where n is an integer starting at 1. Thus, 2.9.4_1 differs from 2.9.4 only in documentation, as does 2.9.4_2, etc.

Create a 2.9.4_1 tag via git tag 2.9.4_1.

Change to the docs directory.

When the 2.9.4 documentation was built, the following environment variables were set (find the variables used to build the current documentation here ):

export MITTO_LATEST='2.9.4'
export MITTO_REL='2.9.4'
export MITTO_RELEASED='^refs/tags/(2.8.([89]|1[0-2])|2.9.[0-4])$'
export MITTO_DATA='/tmp/mitto-tests'
export MITTO_TAGS='(2.8.([89]|1[0-2])|2.9.[0-4])$'

Update those to include our new documentation-only release:

export MITTO_LATEST='2.9.4_1'
export MITTO_REL='2.9.4_1'
export MITTO_RELEASED='^refs/tags/(2.8.([89]|1[0-2])|2.9.[0-4]|2.9.4_1)$'
export MITTO_DATA='/tmp/mitto-tests'
export MITTO_TAGS='(2.8.([89]|1[0-2])|2.9.[0-4]|2.9.4_1)$'

Make all versions of the documentation and view it:

make versions
make serve

If it looks good, publish the documentation to zuar.com:

make publish

Push the tag to github, if desired.