Skip to content

Files

Latest commit

 

History

History

docs

Building the Docs

The EuroPi documentation is built by Sphinx and deployed to GitHub Pages upon pushes to the main branch using GitHub Actions.

If you've made changes to the documentation you'll want to build the docs locally in order ot verify that the build runs without errors and that your changes are rendered as you expect.

In order to build the documentation locally you'll need to install Sphinx and the related dependencies in a virtual environment. Our deployment uses Python 3.8. Install the requirements with:

$ pip install -r docs/requirements.txt

You can then build the documentation locally with:

$ make docs

If successful, the built docs will end up in docs/_build/html/, and the docs can be viewed by opening the index.html file in your browser.

If necessary, you can remove the generated docs with:

$ make clean_docs

Windows

Currently there is no root-level bat file equivalent to the Makefile. In order to build the documents on Windows, you'll have to execute the batch file in the docs dir directly:

> cd docs
> make.bat html

See the root level Makefile for details on the exact command and options we are using to execute Sphinx.

Updating the doc build process requirements

Occasionally, a new requirement is added, or an existing requirement needs to be updated. To do so, first add or update the requirements in docs/requirements.in. Be sure that any newly added requirements are pinned to a specific version. Then, regenerate the docs/requirements.txt file by executing the tool pip-compile:

$ pip-compile docs/requirements.in

pip-compile is part of the pip-tools package and can be installed with the other development requirements by following the instructions in the software README.

Both the docs/requirements.in and the generated docs/requirements.txt files should be committed.