.. SPDX-License-Identifier: GPL-3.0-or-later

.. include:: infra-warning.rst

.. _infra-pages:

Documentation in GitLab Pages
=============================

Since version 6.0 (but also back-ported to later versions of 5.x), the Knot
Resolver documentation is generated by the GitLab CI/CD pipeline. This way we
control the build environment as opposed to ReadTheDocs, which we have been
using in the past.

The relevant CI jobs can be found in the ``docs`` section of
``.gitlab-ci.yml`` in the project root directory (jobs ``docs:build``,
``docs:develop``, ``docs:release``, etc.).

To keep the advantages of having multiple versions of the docs available for
users that cannot update to the latest Knot Resolver, we are leveraging multiple
GitLab features, namely the ability of *Pages* to serve project artifacts
(`currently under-documented by GitLab, but mentioned <gitlab-pages-artifacts_>`_),
and *Environments* to automate the creation of links to said artifacts.

A ``docs:public`` job is also in place to publish our desired version of the
docs directly at https://www.knot-resolver.cz/documentation/latest
(reverse-proxied to https://knot.pages.nic.cz/knot-resolver).

.. note::

    The published version will generally be the latest stable, but we can
    theoretically choose anything -- the job is configured to be available from
    any pipeline.

.. _gitlab-pages-artifacts: https://docs.gitlab.com/ee/ci/jobs/job_artifacts.html#browse-the-contents-of-the-artifacts-archive


Automatic generation
--------------------

The ``docs:build`` job takes care of building the documentation from sources and
exposing it as its artifacts, which are then inherited by subsequent jobs:

* For each commit on a branch, the ``docs:develop`` job is executed to publish
  the docs as a development version. This may be used by users who work with
  nightlies, as well as the development team for making sure the docs look the
  way they want them to. For each branch, an environment is created with the
  name `docs-develop/<branch_name> <docs-develop_>`_.

* For each tag, the ``docs:release`` job is executed to publish the docs as a
  release version. These go into environments named
  `docs-release/<tag_name> <docs-release_>`_.

.. _docs-develop: https://gitlab.nic.cz/knot/knot-resolver/-/environments/folders/docs-develop
.. _docs-release: https://gitlab.nic.cz/knot/knot-resolver/-/environments/folders/docs-release


Environment removal
-------------------

GitLab environments may be un-published using the `Stop` button on the
`Environments screen <envs_>`_. This will hide the environment away, but not
delete it. Stopped environments can be found on the
`Stopped environments tab <stopped-envs_>`_, from which they may also be
re-published or permanently deleted.

Outdated artifacts get automatically deleted by GitLab, but in the case where
the branch does not exist anymore, the environment will stay and the link will
lead to nowhere. These need to be cleaned up manually at the moment, but we may
want to introduce an automated mechanism for this at some point.

.. _envs: https://gitlab.nic.cz/knot/knot-resolver/-/environments
.. _stopped-envs: https://gitlab.nic.cz/knot/knot-resolver/-/environments?page=1&scope=stopped&search=