Documentation (Sphinx)

To generate this documentation, we use the Python documentation generator Sphinx (see Using Sphinx).

The generation process is divided into two stages:

  1. sphinx-apidoc is a tool which scans the whole source code of our application in the integreat_compass directory and generates .rst files out of the Python docstrings. These files are then placed in the docs/src/ref directory.

  2. sphinx-build generates the html documentation out of the .rst files located in the sphinx directory. It merges the static .rst files directly in the docs/src directory together with the files generated in step 1 in docs/src/ref.

Developer Tools

Generate this documentation with https://github.com/digitalfabrik/integreat-compass/blob/develop/tools/make_docs.sh:

./tools/make_docs.sh [--clean]

Apart from the two steps above, this tool also performs the additional tasks:

  • Modify the autogenerated .rst files to improve the readability by removing module paths in headings.

If the --clean parameter is provided, the script will clean all temporary documentation files in the docs/src/ref/ directory as well as the compiled html output in docs/dist. Existing outdated documentation files can cause the generation script to fail if e.g. source files were added or deleted.