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.
Many of our repositories use MyST Markdown.
This is enabled via the
myst-parser Sphinx extension.
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.
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
nox, run this command:
pip install nox
To see a list of available commands, run this command:
For example, we often name our documentation command
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
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
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.txtfile. Assuming a file in this location, run this command:
pip install -r docs/requirements.txt
Look for a
docsrepository. This is auto-generated by Sphinx to help you build the documentation. To build the
htmlfor 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).
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
sphinx-build documentation for more information.