Documentation Generation Guide

Documentation Generation Guide#

Manual Documentation Building#

  1. It is recommended to use virtual environment managed by uv, to encapsulate the dev tools (Python frameworks and other software components) from the system. Create Python 3.11 virtual environment using Python dependency management tool you are using (e.g. Conda, Pipenv, etc…).

    Reference Installation Steps

    uv venv

  2. Install documentation docs dependencies stored in pyproject.toml file.

    sphinx (~5.0.2)
myst-parser (=1.0.0)
sphinxemoji (=0.2.0)
sphinx-design (=0.3.0)
sphinx-book-theme (=1.0.0)
sphinx-togglebutton (=0.3.2)
sphinx-copybutton (=0.5.1)
sphinxcontrib-mermaid (=0.8.1)
sphinx-subfigure (=0.2.4)

    Reference Installation Steps

    uv sync --all-extras --frozen

  3. Go into repository’s root folder and in the activated environment build the documentation:

    sphinx-build -b html docs_src docs

    Reference Installation Steps

    uv run sphinx-build -b html docs_src docs

  4. In repository’s root folder run a HTTP server with the documentation:

    python -m http.server --directory docs 4444

    Then open your browser http://localhost:4444 and see the documentation.

    Reference Installation Steps

    uv run python -m http.server --directory docs 4444

    Then open your browser http://localhost:4444 and see the documentation.

Manual API Docs Source Files Generation#

  1. Go into the project root folder.

  2. Execute following command:

    uv run sphinx-apidoc -o docs_src/api -f -t docs_src/_template  --private --module-first -d 1 --no-toc -e  .
Contents