From 92e60530c0612282ea6aee3989cd3cee47b8adc5 Mon Sep 17 00:00:00 2001
From: =?utf8?q?Oto=20=C5=A0=C5=A5=C3=A1va?= <oto.stava@nic.cz>
Date: Tue, 29 Aug 2023 10:38:13 +0200
Subject: [PATCH] .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.
---
 .gitlab-ci.yml | 70 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 70 insertions(+)

diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
index 641de80a7..d7f16cb04 100644
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
@@ -760,3 +760,73 @@ packaging:fedora_32:
     DISTRO: fedora_32
 
 # }}}
+
+# docs: {{{
+
+docs:build:
+  image: $CI_REGISTRY/packaging/apkg/lxc/fedora-36
+  stage: deploy
+  needs: []
+  script:
+    - git submodule update --init --recursive
+    - apkg build-dep -y
+    - dnf install -y python3-sphinx texinfo doxygen
+    - pip3 install -r doc/requirements.txt
+    - pip3 install sphinx_rtd_theme
+    - meson build_doc -Ddoc=enabled
+    - ninja -C build_doc doc
+  artifacts:
+    paths:
+      - 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
+
+# }}}
-- 
2.47.2