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).

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.

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>.

  • 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>.

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.