The User and API Documentation¶

The documentation of RuNNer consists of two parts:

• the user documentation is built with zensical. This Python project is the successor of Mkdocs, and builds ready-to-publish static web pages from Markdown files.
• the API documentation is built with a custom Python script based on Ford from the docstrings in the source code and fully integrated into the zensical documentation.

The process of building and deploying the documentation happens automaticaly via the CI pipeline.

tl;dr¶

As a developer, here is how to build the docs locally:

uv venv
uv pip install zensical ford
uv run scripts/generate_docs.py
uv run zensical serve

zensical user documentation¶

The central configuration file for the documentation is mkdocs.yml. It contains many comments explaining the functions of most relevant settings. Most importantly, this file contains a nav section:

nav:
  - Home: index.md
[...]

As one can see, this section puts the Markdown files in their correct location on the web page. All Markdown files are contained in the docs/ folder. The structure of this folder is completely arbitrary as long as the correct path is given within the nav section. The sub-folders are just meant for increased readability.

When you make changes to the docs, it is always a good idea to build the documentation locally to see how it looks (formatting ok? are all links working?)

uv venv
uv pip install zensical
uv run zensical serve

spins up a local server that changes the documentation in realtime whenever you make a change.

overrides Directory¶

The homepage of the documentation is not formatted with Markdown but has been overridden with a custom .html page that can be found in the overrides/ directory within the docs/ folder of the project.

Ford API documentation¶

The API documentation of RuNNer is generated through Ford. As we did not like that Ford generates a separate documentation with suboptimal search functionality, we wrote a custom script, built on Ford's excellent source code parsing abilities, that generates Markdown files for each module and inserts them into zensical's nav tree.

To build the API docs locally, run

uv venv
uv pip install ford
uv run scripts/generate_docs.py

This process can take a while, since we generate dependency graphs for all components of the program using graphviz. Either install graphviz and wait, or disable the generation of graphs temporarily in ford_documentation.md.

The main configuration file of Ford is ford_documentation.md. For example, it can be helpful to change the src_dir: src option to a subdirectory of src if you only want to check the documentation for a single module.