Generating the Documentation

This page outlines how to generate the lovely docs you are currently reading!

The docs are generated via mkdocs with Material for MkDocs. All of the docs are markdown files that reside in the mkdocs/ directory, and the docs site is configured via the mkdocs.yml file.

Dependencies

All of the dependencies to build the docs are installed as part of the test dependencies (defined in pyproject.toml). This is obtained by running:

source venv/bin/activate  # Make sure you are in your venv
pip install -e ."[tests]"

Running mkdocs

You can run mkdocs locally by running:

source venv/bin/activate  # Make sure you are in your venv
mkdocs serve

... and then opening your web browser to http://localhost:8000. Errors and warnings will appear in the console output. Please make sure there are none before submitting documentation updates.

Building the docs

The docs are built by running:

source venv/bin/activate  # Make sure you are in your venv
mkdocs build -d docs/

Doing this will generate the docs to the site/ directory. You need to rename this directory to docs/. This directory is not included in the main branch of the repository. Instead, we have another branch called gh-pages where this is committed to. This is what GitHub uses to host the site you are reading right now.