Extending the documentation

Using reStructuredText

Useful resources:

Building a local copy of the docs

  1. Create a Python virtual environment at .venv:

    $ python3 -m venv .venv

  2. Activate the virtual environment:

    $ source .venv/bin/activate

  3. Install the documentation pre-requisites:

    $ pip install -r docs/requirements.txt

  4. Build the documentation:

    $ make -C docs html

  5. Open the documentation in your favorite browser:

    $ <BROWSER> docs/_build/html/index.html

Contributing to the docs

Documentation contributions follow the same workflow as code contributions. Open a pull request (PR) against the develop branch on GitHub, and make sure the build and any pre-commit hooks pass before requesting review (see CONTRIBUTING for the full contributor workflow).

A few things to keep in mind when working on the docs:

  • Format: write documentation in reStructuredText (rST). See the sections above for useful resources. If you add a new page, remember to wire it into a toctree so that Sphinx picks it up.

  • Pre-commit hooks: the project’s pre-commit configuration also checks documentation sources for spelling mistakes, trailing whitespace, and missing newlines at EOF. Install and run the hooks as described in CONTRIBUTING.

  • Verify locally: before opening a PR, build a local copy of the docs (see the previous section) and skim the rendered output for warnings or layout issues. Sphinx emits warnings for broken cross-references and malformed directives, so treat a clean build as the baseline.