From 329b107033012dbc78756995f0be0624303922bd Mon Sep 17 00:00:00 2001 From: =?utf8?q?Oto=20=C5=A0=C5=A5=C3=A1va?= Date: Mon, 18 Mar 2024 10:38:48 +0100 Subject: [PATCH] remove `doc-dev` directory, merge into `doc/dev` --- doc-dev/README.md | 5 --- doc-dev/docs-gitlab-pages.md | 50 ------------------------ doc/dev/index.rst | 7 ++++ doc/dev/infra-pages.rst | 73 ++++++++++++++++++++++++++++++++++++ doc/dev/infra-warning.rst | 5 +++ 5 files changed, 85 insertions(+), 55 deletions(-) delete mode 100644 doc-dev/README.md delete mode 100644 doc-dev/docs-gitlab-pages.md create mode 100644 doc/dev/infra-pages.rst create mode 100644 doc/dev/infra-warning.rst diff --git a/doc-dev/README.md b/doc-dev/README.md deleted file mode 100644 index 1559f7c14..000000000 --- a/doc-dev/README.md +++ /dev/null @@ -1,5 +0,0 @@ -# Knot Resolver developer documentation - -This directory contains documentation for Knot Resolver developers. It is in no -way exhaustive, but may contain some useful information about non-obvious things -about our sources and our CI/CD pipelines. diff --git a/doc-dev/docs-gitlab-pages.md b/doc-dev/docs-gitlab-pages.md deleted file mode 100644 index 739bf05b5..000000000 --- a/doc-dev/docs-gitlab-pages.md +++ /dev/null @@ -1,50 +0,0 @@ -# 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 . - - -## 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/`](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/`](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. diff --git a/doc/dev/index.rst b/doc/dev/index.rst index 5820f7ee0..b340b692a 100644 --- a/doc/dev/index.rst +++ b/doc/dev/index.rst @@ -52,6 +52,13 @@ Welcome to Knot Resolver's documentation for developers and advanced users! manager-dev architecture +.. toctree:: + :caption: Infrastructure + :name: infra-chapter + :maxdepth: 1 + + infra-pages + Indices and tables ================== diff --git a/doc/dev/infra-pages.rst b/doc/dev/infra-pages.rst new file mode 100644 index 000000000..0ca53a553 --- /dev/null +++ b/doc/dev/infra-pages.rst @@ -0,0 +1,73 @@ +.. 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 `_), +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/ `_. + +* For each tag, the ``docs:release`` job is executed to publish the docs as a + release version. These go into environments named + `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 `_. This will hide the environment away, but not +delete it. Stopped environments can be found on the +`Stopped environments tab `_, 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= diff --git a/doc/dev/infra-warning.rst b/doc/dev/infra-warning.rst new file mode 100644 index 000000000..3018df0ef --- /dev/null +++ b/doc/dev/infra-warning.rst @@ -0,0 +1,5 @@ +.. warning:: + + This section documents semi-public parts of the internal infrastructure for + `CZ.NIC `_ developers. It is probably not very useful to + external users (but do feel free to study). -- 2.47.2