Documentation practices

EdgeGraph follows a strict rule of 100% documentation-of-code coverage, plus any necessary narrative documentation. Sphinx is used to build documentation, which is hosted on ReadTheDocs. GitHub Actions deploys documentation builds automatically.

Documentation of code is kept as close to the code as possible – in Python docstrings for the relevant modules, classes, and functions. These are written in reStructuredText format, with Sphinx extensions available. Narrative documentation (along with docs configuration and indexing) is kept in the docs/ folder.

Building documentation

Documentation can be built locally using the Sphinx makefile in the docs/ folder. Ensure you have the following prerequisites:

1. PlantUML installed (see https://plantuml.com/ )

2. Pip prerequisites: pip install .[development]

Then, simply run make clean html to build docs locally. Output will be placed in docs/_build/. You may also inspect the output of make help to show additional formats that can be built.

Advanced documentation control

Some more-than-trivial tasks are performed while building the documentation. Some examples are checking the Git repo status (to add a banner for docs built on non-master branches), version number checks, and cleaning old build data. As usual for Sphinx, the configuration is maintained in docs/conf.py.

Coverage assessment

Documentation-of-code coverage is also assessed by Sphinx, using the coverage extension. Though this is run by GitHub Actions against all pull requests, you may also assess coverage locally by using make coverage. A file _build/coverage/python.txt will be created; this contains the coverage table. Ensure that the bottom row (TOTAL) is marked as 100.00%.