Setup, build and use
====================

The documentation for PRE_ is
straightforward to implement.

This section depicts the steps to locally setup,
build and use the documentation website.

Setup
-----

.. note::

    Adapt the ``python`` and the paths in the following commands
    to reflect the current installation (e.g. Linux VS Windows).
    This is also worth knowing for the rest of the documentation.

Requirements
************

- Git_: Version control system
- UV_: Python manager (also works with
  base Python with some adaptations)

Cloning the ``docs`` repository
*******************************

.. code-block:: bash

    git clone https://gitlab.com/project-rat-extras/docs

The static documentation website is now ready to be built.

Build
-----

Navigate into the repository then into its inner ``docs/docs``
subdirectory in order to build the static HTML files using
the makefiles generated by Sphinx:

.. code-block:: bash

    cd docs/docs
    uv run make html

First time running the second command will trigger UV to build
a venv within the repo to download and install dependencies
specified in the ``pyproject.toml`` file such as ``sphinx``
and its Mermaid_ module.

It will then use Sphinx to render HTML files inside the
``docs/docs/build`` subdirectory with an ``index.html`` as an
entry point for the static website. Open it in a browser to
enjoy the documentation

Update
******

Whenever content is modified, static pages should be rebuilt using
the above command. However some changes are more subtle than over
and Sphinx might not catch it.

When this happens make sure to clean the build directory before
building again:

.. code-block:: bash

    uv run make clean
    uv run make html

Use
---

As explained before this documentation is built using Sphinx.
It utilizes plain text files in the format of reStructuredText_
to generate rich HTML static pages using themes and other web
logic to style and customize most of it.

In this form all ``.rst`` files define an HTML page to be
rendered by Sphinx. They can be nested in several subdirectories
for leaner structure as it is the case for these per-repository
documentations.

All static resources such as images and styles are gathered under
a ``_static`` directory that will be copied next to the rendered
HTML upon building in order to containerize everything.

Configuration
*************

Sphinx defines a ``docs/docs/source/conf.py`` configuration file
for users to manipulate the logic and variables of the website.
See `Sphinx configuration`_ for more information.

For us it simply defines some base paths for Sphinx to find
local items such as the local Meral theme, as well as some
other Python modules to extend Sphinx_ such as Mermaid_ for
graphs using the `Mermaid module`_.

Deploy
------

Sphinx_ and GitLab_ make it easy to deploy
simple static websites through `GitLab pages`_.

Deployment is done via the `.gitlab-ci.yml`_
file defined in the `docs repository`_:

.. code-block:: yaml

    # Docker image used
    image: python:3.13.7-alpine
    create-pages:
    pages:
        # Folder containing files to be exposed at the pages URL
        publish: public
    rules:
        # Ensures that only pushes to default
        # branch will trigger a pages deploy
        - if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH
    # Functions to execute before the build script
    before_script:
        - pip install -U sphinx sphinxcontrib-mermaid
    # Actual build script
    script:
        - sphinx-build -b html ./docs/source public

This simple file ensures every push to the default branch (e.g.
the ``main`` branch) triggers a CI/CD pipeline to spin up a
``python:3.13.7-alpine`` Docker image on a GitLab runner to
execute the following steps:

1. Install the `docs repository`_ dependencies:
   Sphinx_ and its `Mermaid module`_.

2. Build the static HTML website into a ``public`` directory
   that will be exposed by GitLab pages as the static website.


.. Links
.. _Docs: https://gitlab.com/project-rat-extras/docs
.. _docs repository: https://gitlab.com/project-rat-extras/docs
.. _Git: https://git-scm.com/
.. _GitLab: https://gitlab.com/
.. _GitLab pages: https://docs.gitlab.com/user/project/pages/
.. _.gitlab-ci.yml: https://gitlab.com/project-rat-extras/docs/-/blob/main/.gitlab-ci.yml?ref_type=heads
.. _Mermaid: https://mermaid.ai/web/
.. _Mermaid module: https://github.com/mgaitan/sphinxcontrib-mermaid
.. _PRE: https://gitlab.com/project-rat-extras
.. _reStructuredText: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
.. _Sphinx: https://www.sphinx-doc.org/en/master/index.html
.. _Sphinx configuration: https://www.sphinx-doc.org/en/master/usage/configuration.html
.. _UV: https://docs.astral.sh/uv/