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 ycms 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/charludo/ycms/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.