Build Sphinx Documentation
==========================

The file ``ci-docs.yml`` defines jobs to build and publish
Sphinx documentation pages to GitLab Pages.


``build-docs``
--------------

This jobs builds the Sphinx documentation for the current merge request,
branch or tag and uploads it as a build artifact.

Configuration is done using environment variables:

- ``PYTHON_INSTALL_METHOD: pip``, method to install docs build dependencies.
  Can either be ``pip`` (default) or ``pixi`` (preferable if conda packages are needed)
- ``PIP_EXTRAS: doc``, a comma-separate list of extras to install when using pip.
- ``PIXI_TASK: doc``, if using pixi, the name of the pixi task that builds the documentation.
- ``OUTPUT_DIR: docs/build/html``, output directory of the build, this will be uploaded as artifact.


``deploy_docs_env``
-------------------

This job creates a GitLab Environment so that the build documentation
can be reviewed in a merge request.

``pages``
---------

This job collects the test artifacts of the ``build-docs`` step
and publishes them GitLab Pages using `gitlab-multi-version-sphinx <https://gitlab.cta-observatory.org/cta-computing/common/gitlab-multi-version-sphinx>`_.
This job only runs on the default branch and on tag builds.
