.gitlab-ci.yml: use environments for documentation versioning

This leverages Environments on GitLab to expose different versions of
Knot Resolver docs. The `docs:build` job builds the documentation and
exposes it via job artifacts. Then `docs:develop` (for branches) and
`docs:release` (for tags) take these artifacts and expose them via an
Environment link (an example of this in action may be seen at
[https://gitlab.nic.cz/ostava/knot-resolver/-/environments]).

There is also an optional, manually runnable `docs:public` job, which,
when run, propagates the documentation to the main GitLab Pages of the
project (e.g. [https://knot.pages.nic.cz/knot-resolver]) - this will
probably be mostly used for the latest release, although this setup
pretty much allows us to swap it for whatever version we like at any
time.

diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
index 69371e3140f19d44f69d99198e029f4aa25b1a5a..72df5c73f4becd4db8b188dfd9c44a33ec227aad 100644 (file)
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
@@ -644,7 +644,9 @@ pkg:alma-9:
 #  allow_failure: true  # SUSE is always special
 # }}}
 
-pages:
+# docs: {{{
+
+docs:build:
   image: $CI_REGISTRY/packaging/apkg/lxc/fedora-36
   stage: deploy
   needs: []
@@ -656,7 +658,58 @@ pages:
     - pip3 install sphinx_rtd_theme
     - meson build_doc -Ddoc=enabled
     - ninja -C build_doc doc
-    - mv doc/html public
   artifacts:
     paths:
-      - public
+      - doc/html
+
+# This job deploys the Knot Resolver documentation into a development
+# environment, which may be found at
+# <https://gitlab.nic.cz/knot/knot-resolver/-/environments/folders/docs-develop>.
+# The actual URL is found in the `environment.url` property, where
+# $CI_PROJECT_NAMESPACE will be "knot" on the upstream GitLab.
+docs:develop:
+  stage: deploy
+  needs:
+    - docs:build
+  except:
+    refs:
+      - tags
+  script:
+    - echo "Propagating artifacts into develop environment"
+  artifacts:
+    paths:
+      - doc/html
+  environment:
+    name: docs-develop/$CI_COMMIT_REF_NAME
+    url: https://$CI_PROJECT_NAMESPACE.pages.nic.cz/-/knot-resolver/-/jobs/$CI_JOB_ID/artifacts/doc/html/index.html
+
+# This job deploys the Knot Resolver documentation into a release environment,
+# which may be found at
+# <https://gitlab.nic.cz/knot/knot-resolver/-/environments/folders/docs-release>.
+# The actual URL is found in the `environment.url` property, where
+# $CI_PROJECT_NAMESPACE will be "knot" on the upstream GitLab.
+# The job requires the `DOCS_ENV_NAME` variable to be set by the user.
+docs:release:
+  stage: deploy
+  needs:
+    - docs:build
+  only:
+    refs:
+      - tags
+  script: echo "Propagating artifacts into release environment"
+  artifacts:
+    paths:
+      - doc/html
+  environment:
+    name: docs-release/$CI_COMMIT_TAG
+    url: https://$CI_PROJECT_NAMESPACE.pages.nic.cz/-/knot-resolver/-/jobs/$CI_JOB_ID/artifacts/doc/html/index.html
+
+# This job deploys the current docs as <https://knot.pages.nic.cz/knot-resolver>
+docs:public:
+  stage: deploy
+  needs:
+    - docs:build
+  script: mv doc/html public
+  when: manual
+
+# }}}