Building the documentation

You can create the html documentation locally. The documentation is generated using sphinx from the files located under docs/source onto the folder docs/build.

We rely on some external packages to automate the generation of the documentation:

• To generate automatic documentation for API, we use sphinxcontrib-apidoc.

• To automatically generate the documentation for different versions of pyddg, we use sphinx-multiversion.

• To generate a coverage report, we use the coverage extension.

Setup

If you haven’t set up your development environment already, see Installation. Now in your directory pyddg run

poetry shell

which will spawn a new poetry shell.

Building the documentation quickly

To create the whole documentation for the current state of the repository, execute from pyddg directory:

make -C docs/ html

This command is usefull for quick iteration as results are cashed, so only modified files are computed again.

Note though that this command bypasses version information and differs in that way from the command run in the CI pipeline to build the documentation.

You can specify build options to the underlying sphinx command.

export SPHINXOPTS='-j auto'
make -C docs html

You can clean the build directory manually using this command:

make -C docs/ clean

To clean before building run:

make -C docs/ docs

which is equivalent to running

make -C docs/ clean
make -C docs/ html

To visualize the html pages you can run:

firefox docs/build/index.html

Building the current version of the documentation

To create the whole documentation for the current branch, execute from pyddg directory:

python3 test.py -d

This is the default used in the CI pipeline, so succeeding in running this command should ensure that the pipeline will pass for the build of the documentation.

Since the build is based on the current branch, it will not take any non-commited changes into account and a detached head will result in an error.

Also, running this command will automatically clean the build directory before running and no caching will be performed.

You can build the docs using multiple cores with:

python3 test.py -d -- -j auto

To visualize the documentation for the current branch in a browser you can run:

firefox docs/build/pyddg/doc/<current-branch-name>/index.html

For example to visualize the documentation for the develop branch run:

firefox docs/build/pyddg/doc/develop/index.html

Building all the versions of the documentation

To build all the versions of the documentation, execute from pyddg directory:

python3 test.py -D

This behavior must be triggered manually in the CI pipeline to run.

This command will as well clean the build folder before running.

It is recommended to run this command on multiple cores if you have some:

python3 test.py -D -- -j auto

Since the multiple versions of the documentation are interacting with each other via javascript, you need to spawn a webserver to visualize them properly

python3 -m http.server --directory docs/build &
firefox localhost:8000

API Documentation Coverage

Check what parts of the library are covered by the API documentation.

make -C docs/ coverage

and find the list of undocumented parts in pyddg/docs/build/coverage/python.txt.