+++ /dev/null
-# Knot Resolver documentation in GitLab Pages
-
-Since version 6.0 (but possibly at some point back-ported to older versions),
-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](https://docs.gitlab.com/ee/ci/jobs/job_artifacts.html#browse-the-contents-of-the-artifacts-archive)),
-and *Environments* to automate the creation of links to said artifacts.
-
-A `docs:public` job is also in place to publish our desired version (probably
-the latest stable, but we can theoretically choose anything) of the docs
-directly at <https://knot.pages.nic.cz/knot-resolver>.
-
-
-## 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>`](https://gitlab.nic.cz/knot/knot-resolver/-/environments/folders/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>`](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](https://gitlab.nic.cz/knot/knot-resolver/-/environments).
-This will hide the environment away, but not delete it. Stopped environments can
-be found on the
-[Stopped environments tab](https://gitlab.nic.cz/knot/knot-resolver/-/environments?page=1&scope=stopped&search=),
-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 an
-automated mechanism may be introduced later.
--- /dev/null
+.. 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=
projects / thirdparty / knot-resolver.git / commitdiff
