Generating Documentation

Generating Documentation#

Sphinx is used to create this documentation from the files in the docs directory and from the docstrings in the code. This is done automatically with each merge into the main branch, see the GitHub Action workflow CI-docs.

Docstrings are written in RST format following the numpydoc standard. Documentation pages are written in Markdown (MyST flavor, although RST is also possible (but not preferred).

Caution

Each application requires a small RST file (e.g., get_file_from_db.rst) to avoid Sphinx warnings regarding duplicated labels (sphinx generates those pages using the sphinx.autodoc extension)

Building#

For writing and testing documentation locally:

    cd docs
    make clean
    make html

This is especially recommended to identify warnings and errors by Sphinx (e.g., from badly formatted docstrings or RST files). The documentation can be viewed locally in a browser starting from the file ./build/html/index.html.

Hints for Markdown#

  • links to other files relative to current file: [mongoDB databases](databases.md#databases) results in mongoDB databases.

Contents