Read the Docs
=====================================

This template triggers a new documentation build on the Read the Docs platform
via its REST API.


Usage
-----

In your project's ``.gitlab-ci.yml``:

.. code-block:: yaml

    include:
      - project: "bytecode-solutions/core/core-gitlab-templates"
        file: "releases/read_the_docs.yml"

Parameters
----------

``image``
    The Docker image used to run the trigger job.
    Default: ``python:latest``

``branch``
    The branch on which the job should be executed.
    Default: ``release``

``stage``
    The pipeline stage in which the job is executed.
    Default: ``release``

``project_name``
    The Read the Docs project slug.

``version``
    The documentation version to trigger.
    Default: ``latest``

Behavior
--------

The job performs the following steps:

1. Installs ``Sphinx`` and the project theme (optional but common)
2. Sends an authenticated POST request to the Read the Docs API to start a build

The job runs when the pipeline branch matches the configured ``branch`` input.

Environment Variables
---------------------

``READ_THE_DOCS_TOKEN``
    A Read the Docs API token with permission to trigger builds.

.. tip::

   You can generate a Read the Docs API token from your account settings.
   Store it as a **masked GitLab CI variable** for security.