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#

Many of our repositories use MyST Markdown. This is enabled via the myst-parser Sphinx extension.

reStructuredText#

The default markup language used by Sphinx is reStructuredText. It is a rich and extensible way to write content for our documentation. See the Sphinx reStructuredText documentation for an in-depth guide of how to use it.

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 often use the nox command line tool to 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, run this command:

pip install nox

To see a list of available commands, run this command:

nox -l

For example, we often name our documentation command docs. To install the requirements for documentation and build them locally, run:

nox -s docs

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

We often add an extra parameter to instead run a live server via the sphinx-autobuild extension. To build docs with a live serve that auto-reloads as you change things, run this command:

nox -s docs -- live

Note that this will only work for repositories that have a noxfile.py added.

Building with `Makefile`s#

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

To do so, follow these steps:

Install the requirements for the documentation. This is often in a docs/requirements.txt file. Assuming a file in this location, run this command:
```
pip install -r docs/requirements.txt
```
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 this command:
```
cd docs
make 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.