7.2. Documentation

The vantage6 framework is documented on this website. This page describes how this documentation is created and how to build the documentation locally.

7.2.1. How this documentation is created

The source of the documentation you are currently reading is located here, in the docs folder of the vantage6 repository itself.

To build the documentation locally, there are two options. To build a static version, you can do make html when you are in the docs directory. If you want to automatically refresh the documentation whenever you make a change, you can use sphinx-autobuild. Assuming you are in the main directory of the repository, run the following commands:

# install requirements to run documentation (only required once)
pip install -r docs/requirements.txt

# run documentation interactively
make devdocs
# or alternatively, if you don't have make
sphinx-autobuild docs docs/_build/html --watch .

Then, you can access the documentation on http://127.0.0.1:8000. The --watch option makes sure that if you make changes to either the documentation text or the docstrings, the documentation pages will also be reloaded.

Note

The command make devdocs does not build the function documentation by default, because building that interactively is slow. If you need to build the function documentation locally, you can do so by either running make html or make devdocs FUNCTIONDOCS=true.

Note

This documentation also includes some UML diagrams which are generated using PlantUML. To generate these diagrams, you need to install Java. PlantUML itself is included in the Python requirements, so you do not have to install it separately.

This documentation is automatically built and published on a commit (on certain branches, including main). Both Frank and Bart have access to the vantage6 project when logged into readthedocs. Here they can manage which branches are to be synced, manage the webhook used to trigger a build, and some other -less important- settings.

The files in this documentation use the rst format, to see the syntax view this cheatsheet.