Documentation Guide

Building the Docs

The documentation build process is stored in the Makefile. Building docs requires Python to be installed, and most steps will create a virtualenv (doc_venv) which install the documentation generation toolset.

Run make html to generate html documentation in _build/html.

Run make reload to get a live reload in your browser (refreshes on document save).

To check the formatting of documentation, run make lint. This will be done in Jenkins to validate the documentation, so please do this before you create a patchset.

To check spelling, run make spelling. If there are additional words that are correctly spelled but not in the dictionary (acronyms, trademarks, etc.) please add them to the dict.txt file.

Writing Docs

Docs written using sphinx: http://www.sphinx-doc.org

Documentation is done in reStructuredText (.rst) or Markdown (.md), but only .rst files can use certain features like embedded diagrams.

reStructuredText Primer: http://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html

Creating new Versions of Docs

To change the version shown on the built site, change the versions variable in conf.py.

There is a make versioned target which will build all versions published on the remote to _build. Note that we’re using a fork of the upstream version of the sphinxcontrib-versioning module, as the original isn’t actively maintained, and we needed it to be able to handle the symlink checkouts of other repos that are incorporated.