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 `_. This job only runs on the default branch and on tag builds.