Building and editing documentation¶
The documentation lives in docs/source/ and uses Sphinx with the Furo theme.
Pages can use reStructuredText (.rst) or MyST Markdown (.md). Run the
commands below from the repository root.
Build locally¶
Use a Python version supported by pyproject.toml and install the locked
documentation dependencies:
uv sync --frozen --group docs
Install a Java runtime and Graphviz (including the dot command) for diagram
rendering. Sphinx uses the PlantUML JAR checked into docs/source/; a separate
PlantUML installation is not needed locally. Check that both tools are on your
PATH:
java -version
dot -V
Build HTML with unresolved-reference checks and warnings treated as errors:
uv run --frozen sphinx-build -b html -n -W --keep-going docs/source docs/build/html
Open docs/build/html/index.html in a browser. For a clean rebuild, add
-E -a to the command. To use the Makefile from the repository root:
make -C docs html SPHINXOPTS="-n -W --keep-going"
make -C docs clean html SPHINXOPTS="-n -W --keep-going"
The build initializes Django through docs/source/conf.py, so it needs the
project environment, not just a standalone Sphinx installation. It does not
require a running application, database migrations, or a database reset.
Hosted builds¶
Read the Docs uses .readthedocs.yaml to select Python, install the frozen
documentation dependencies, and provide diagram tools. Sphinx enables
unresolved-reference warnings in conf.py, and the hosted configuration treats
warnings as build failures. Pull-request previews depend on the Read the Docs
project’s integration settings. See CI/CD for the full build
configuration.