Structure

The docs repository is structured as a Sphinx project generated from the sphinx-quickstart command in combination with the UV CLI:

docs/
├── docs/           ← Sphinx core documentation directory
│   ...
├── src/            ← Python project sources (mostly empty)
│   ...
├── .gitignore      ← Git ignored items (e.g. build)
├── .gitlab-ci.yml  ← GitLab CI/CD config for GitLab pages
├── .python-version ← Python version to use (detected by UV)
├── CHANGELOG.md    ← Changelog for evolution tracking
├── LICENSE.md      ← MIT license file
├── pyproject.toml  ← Python project specifications
├── README.md       ← Repository simple information
├── uv.lock         ← UV lock file for dependencies versions

The docs/src is there only to provide an entry point for UV to run commands from the Python module root. The heart of the documentation lies in the docs/docs subdirectory.

The docs/docs subdirectory

This directory is organized in the following manner:

docs/docs/
├── make.bat            ← Windows wrapper for Makefile
├── Makefile            ← Makefile helper to build docs
├── build/              ← Actual static website (generated)
│   │   ...
├── source/             ← Sources to generated documentation
    ├── _static/        ← Static files (images, CSS, ...)
    ├── _templates/     ← HTML templates
    ├── _themes/        ← Local Sphinx themes (e.g. Meral)
    │   ├── meral/
    ├── graphs/         ← Mermaid graph files
    │   ...
    ├── repo-<name>/    ← Repository specific documentation
    │   ...               (subsections)
    ├── conf.py         ← Sphinx configuration script
    ├── index.rst       ← Home page of documentation static site
    ├── <name>.rst      ← Rest of home subsections documentation

Important

Most commands regarding build should be run from this docs/docs subdirectory.

Such structure is achieved by following the basic Sphinx quickstart setup by separating build and source directories.

The use of subdictories per documented project is quite simple yet very powerful and allow for clear separation while maintaining the ability to cross-reference between them.