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 lunes_cms 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/lunes-cms/blob/develop/tools/generate_documentation.sh:

./tools/generate_documentation.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.