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