Documentation (Sphinx)
To generate this documentation, we use the Python documentation generator Sphinx (see Using Sphinx).
The generation process is divided into two stages:
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 thedocs/src/ref
directory.sphinx-build generates the html documentation out of the
.rst
files located in the sphinx directory. It merges the static.rst
files directly in thedocs/src
directory together with the files generated in step 1 indocs/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.