Writing documentation#

All of the team’s repositories are documented using the Sphinx documentation engine. This page contains resources to help you understand Sphinx and the configurations we commonly use in our repositories.

MyST Markdown#

Our repositories use MyST Markdown. This is enabled via the myst-parser Sphinx extension.

Build documentation locally#

There are a few ways to build the documentation in our repositories. Some depend on certain tools being installed. Here are a few common ways to do so, from most- to least-automated.

Building with nox#

We use the nox command line tool to automate the build documentation locally. nox is a tool for quickly running commands in an isolated build environment. It is similar to Make, but with a Python configuration and with local build environments that are isolated to each job that you run.

nox is configured with a file called noxfile.py.

To install nox, follow the steps in Nox’s documentation.

To see a list of available commands, run

nox -l

To install the requirements for documentation, build them locally, and have a live preview, run

nox -s docs -- live

Note

If you don’t want the live preview, run

nox -s docs

This will place the built HTML files in docs/_build/html for you to inspect as you wish.

Building with Makefiles#

Many of our repositories also have a Makefile that runs commands in your currently-active Python environment.

To do so, follow these steps:

  1. Install the requirements for the documentation. This is often in a docs/requirements.txt file. Assuming a file in this location, run

    pip install -r docs/requirements.txt

  2. Look for a Makefile in the docs repository. This is auto-generated by Sphinx to help you build the documentation. To build the html for our documentation, run

    make -C docs html

    It will put the built documentation in _build/html (depending on our configuration this may change a bit).

Building with sphinx-build#

This is the way to have the most control over a documentation’s build, but is also the most cumbersome to do repetively.

To do so, install the documentation requirements (see Building with Makefiles and run a command like so:

sphinx-build docs docs/_build/html

See the sphinx-build documentation for more information.