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

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:

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:

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:

# 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.