Building the documentation#

Get started#


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


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:


Run the tests:


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.


If the tests are failing:

  • Ensure your dependencies are up-to-date:

    pip install pip-tools
  • Clean and re-build the documentation:

    make clean

Build the documentation#

Build the documentation in all languages into build/:


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 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