[WIP] doc: Make automatic deployment of versioned documentation possible

.gitlab-ci.yml

@@ -48,7 +48,7 @@ generate-docs:
 # CI_OUTPUT_DIR: doc_output
 # EOS_ACCOUNT_PASSWORD: xxx
 # EOS_ACCOUNT_USERNAME: xxx
-# EOS_PATH: /eos/project/k/key4hep/www/key4hep/podio
+# EOS_DEPLOY_BASE_PATH: /eos/project/k/key4hep/www/key4hep/podio
 # METHOD: rsync
 # are set in the repository https://gitlab.cern.ch/key4hep/podio,
 # which mirrors https://github.com/AIDASoft/podio
@@ -62,13 +62,18 @@ deployment:
   only:
     refs:
       - master
+      - versioned-docs
+      - /^v\d+-\d+-?\d+?$/
   # need the doxygen artifacts for this step
   dependencies:
     - generate-docs
   stage: deploy
+
   # see see https://gitlab.cern.ch/ci-tools/ci-web-deployer
   image: gitlab-registry.cern.ch/ci-tools/ci-web-deployer:latest
+  before_script:
+    - if [ -z "$CI_COMMIT_BRANCH" ]; then TARGET_DEPLOY_DIR=$CI_COMMIT_TAG; else TARGET_DEPLOY_DIR=$CI_COMMIT_BRANCH; fi
+    - export EOS_PATH=$EOS_DEPLOY_BASE_PATH/_contents/$TARGET_DEPLOY_DIR
   script:
     - deploy-eos
-  before_script: []
   after_script: []

doc/_templates/versions.html

@@ -0,0 +1,79 @@
+<div class="rst-versions" data-toggle="rst-versions" role="note" aria-label="versions">
+    <span class="rst-current-version" data-toggle="rst-current-version" id="current-version-span">
+        <span class="fa fa-caret-down"></span>
+    </span>
+    <script>
+        document.getElementById("current-version-span").insertAdjacentText('afterbegin', `Version: ${window.location.href.split('/').at(-2)}`)
+    </script>
+
+    <div class="rst-other-versions" id="other-versions-div">
+    </div>
+    <script>
+        /** Parse all available versions from the directory listing content
+         */
+        function getAvailableVersions(contents) {
+            // Take a DOMParser to get to the links
+            let parser = new DOMParser();
+            let doc = parser.parseFromString(contents, 'text/html');
+
+            let links = doc.querySelectorAll('a');
+            let availableVersions = [];
+            links.forEach(link => {
+                let href = link.getAttribute('href');
+                if (href.endsWith('/') && !href.startsWith('/')) {
+                    availableVersions.push(link.textContent.replace(/\/$/, ''));
+                }
+            });
+
+            return availableVersions;
+        }
+
+        /** Sort versions in descending order, ordering "non-versions" to the top
+         */
+        function sortVersions(v1, v2) {
+            const rgx = /^v(\d+)-(\d+)(?:-(\d+))?$/
+            const m1 = v1.match(rgx);
+            const m2 = v2.match(rgx);
+
+            // If only one matches, that has to go down, otherwise we keep the order
+            if (!m1 && m2) return -1;
+            if (m1 && !m2) return 1;
+            if (!m1 && !m2) return 0;
+
+            const intV1 = parseInt(m1[1], 10) * 10000 + parseInt(m1[2], 10) * 100 + parseInt(m1[3] || 0, 10);
+            const intV2 = parseInt(m2[1], 10) * 10000 + parseInt(m2[2], 10) * 100 + parseInt(m2[3] || 0, 10);
+
+            return intV2 - intV1;
+        }
+
+        const other_versions = document.getElementById("other-versions-div");
+        other_versions.innerHTML = '';
+
+        // Dynamically determine the versions by checking the directory one
+        // level up and populate the version list from there
+        const baseUrl = window.location.href.split('/').slice(0, -2).join('/');
+        fetch(baseUrl)
+            .then(response => response.text())
+            .then(contents => {
+                const availableVersions = getAvailableVersions(contents);
+
+                availableVersions.sort(sortVersions);
+
+                const versionList = document.createElement("dl");
+                const header = document.createElement("dt");
+                header.textContent = "Versions";
+                versionList.appendChild(header)
+
+                availableVersions.forEach(v => {
+                    const vElem = document.createElement("dd");
+                    const vLink = document.createElement("a");
+                    vLink.href = `${baseUrl}/${v}`;
+                    vLink.textContent = v;
+                    vElem.appendChild(vLink);
+                    versionList.appendChild(vElem);
+                });
+
+                other_versions.appendChild(versionList);
+            });
+    </script>
+</div>

doc/conf.py

@@ -51,7 +51,7 @@
 source_suffix = {".rst": "restructuredtext", ".md": "markdown"}
 
 # Add any paths that contain templates here, relative to this directory.
-# templates_path = ["_templates"]
+templates_path = ["_templates"]
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.

doc/web-deploy/README.md

@@ -0,0 +1,28 @@
+# Versioned documentation deployment
+
+- Assumed to be deployed via eos using a folder structure like this
+```console
+.
+├── _contents
+│   ├── vXX-YY
+│   └── master
+├── index.html
+```
+  - Each version / tag gets a new folder and the `master` / develop version is
+    continually updated
+  - The `_contents` folder has to configured to have *Directory Browsing* enabled
+    since that will be used to determine the available versions (each top-level
+    folder in here will be considered a version). This is achieved via `echo
+    "Options +Indexes > _contents/.htaccess"`
+- The `version.html` "template" fetches the directory from `_contents`, extracts
+  the available directories (via their links) and creates a sorted list of
+  versions before dynamically populating the read-the-docs bit for version
+  selection
+- gitlab ci takes care of copying the generated contents to the correct
+  subfolder of `_contents` depending on whether it has been triggered by a tag
+  or by a push to master
+- Documentation for versions that are added post-hoc need a small adaption of
+  their (sphinx generated) `index.html`; the `version.html` template has to be
+  copied verbatim to the bottom, but above the navigation enabling.
+- The `index.html` in this folder has to be placed into the same folder where
+  also `_contents` is

doc/web-deploy/index.html

@@ -0,0 +1,11 @@
+<!DOCTYPE html>
+<html lang="en">
+
+<head>
+    <title>Redirecting to latest release</title>
+    <meta charset="utf-8">
+    <meta http-equiv="refresh" content="0"; url="./_contents/master/index.html">
+    <link rel="canonical" href="https://key4hep.web.cern.ch/podio/_contents/master/">
+</head>
+
+</html>