|
|
|
# Knot Resolver documentation in GitLab Pages
|
|
|
|
|
|
|
|
Since version 6.0 (but possibly 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. |