Structure
=========

The `docs repository`_ is structured as a Sphinx_ project
generated from the ``sphinx-quickstart`` command in
combination with the UV_ CLI:

.. code-block:: text

    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:

.. code-block:: text

    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.

.. Links
.. _docs repository: https://gitlab.com/project-rat-extras/docs
.. _Sphinx: https://www.sphinx-doc.org/en/master/index.html
.. _UV: https://docs.astral.sh/uv/