Building the documentation

Get started

Note

Building the documentation requires Python 3.8 or greater.

Create a virtual environment using Python 3 with pyenv virtualenv docs or:

sudo apt install python3-venv
python3 -m venv .ve
source .ve/bin/activate

Initialize and update submodules:

git submodule init
git submodule update

Note

If you need to change a submodule, it’s simplest to edit .gitmodules, remove the submodule, then run the above. For example:

rm -rf .git/modules
rm -rf path/to/submodule
git submodule init
git submodule update
cd path/to/submodule
git checkout desired-branch

Run all commands on this page within this virtual environment.

Install the requirements:

pip install -r requirements.txt

Run tests

Build the documentation:

make

Run the tests:

pytest

To replicate the GitHub Actions workflow, you also need to run the tests from the standard maintenance scripts.

test_search will report failures if you have not yet pushed your branch to GitHub because the search index is only built for a branch once you push it. Once your PR passes, the local tests are expected to pass.

Troubleshoot

If the tests are failing:

• Ensure your dependencies are up-to-date:

  pip install pip-tools
  pip-sync
  

• Clean and re-build the documentation:

  make clean
  make
  

Build the documentation

Build the documentation in all languages into build/:

make

Build the source language only:

make source

Build a translation only:

make es

Remove all built files:

make clean

If you edited release-schema.json or meta-schema-patch.json, update files with:

python manage.py pre-commit

Sphinx, which builds the documentation, doesn’t watch directories for changes. To regenerate the documentation and refresh the browser whenever changes are made, run:

make autobuild

Otherwise, view the documentation by running a local web server:

python -m http.server --directory build