From 996858a902a99a899aaf4cb50b5bd08b008283ab Mon Sep 17 00:00:00 2001
From: tmadlener <thomas.madlener@desy.de>
Date: Fri, 23 Aug 2024 16:56:25 +0200
Subject: [PATCH 1/7] Try to deploy to different path

---
 .gitlab-ci.yml | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
index eddf40b01..06290e526 100644
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
@@ -62,10 +62,15 @@ deployment:
   only:
     refs:
       - master
+      - versioned-docs
   # need the doxygen artifacts for this step
   dependencies:
     - generate-docs
   stage: deploy
+
+  variables:
+    EOS_PATH: $EOS_DEPLOY_BASE_PATH/test_deplay_path
+
   # see see https://gitlab.cern.ch/ci-tools/ci-web-deployer
   image: gitlab-registry.cern.ch/ci-tools/ci-web-deployer:latest
   script:

From 66cf6342c96a7e36550a622ad847b5900ceacaf2 Mon Sep 17 00:00:00 2001
From: tmadlener <thomas.madlener@desy.de>
Date: Fri, 23 Aug 2024 17:13:57 +0200
Subject: [PATCH 2/7] Create an output folder depending on tag or branch

---
 .gitlab-ci.yml | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
index 06290e526..2721c6f1d 100644
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
@@ -73,7 +73,9 @@ deployment:
 
   # 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/test_deploy/$TARGET_DEPLOY_DIR
   script:
     - deploy-eos
-  before_script: []
   after_script: []

From b486f053c9e52fba3fdef70c5518e2099ae19c48 Mon Sep 17 00:00:00 2001
From: tmadlener <thomas.madlener@desy.de>
Date: Fri, 23 Aug 2024 17:30:58 +0200
Subject: [PATCH 3/7] Choose better name for contents folder

---
 .gitlab-ci.yml | 7 ++-----
 1 file changed, 2 insertions(+), 5 deletions(-)

diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
index 2721c6f1d..f851e5596 100644
--- a/.gitlab-ci.yml
+++ b/.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
@@ -68,14 +68,11 @@ deployment:
     - generate-docs
   stage: deploy
 
-  variables:
-    EOS_PATH: $EOS_DEPLOY_BASE_PATH/test_deplay_path
-
   # 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/test_deploy/$TARGET_DEPLOY_DIR
+    - export EOS_PATH=$EOS_DEPLOY_BASE_PATH/_contents/$TARGET_DEPLOY_DIR
   script:
     - deploy-eos
   after_script: []

From 5180cfa623af0b1a82f624899919322d9dcb40c9 Mon Sep 17 00:00:00 2001
From: tmadlener <thomas.madlener@desy.de>
Date: Fri, 23 Aug 2024 17:31:18 +0200
Subject: [PATCH 4/7] Add dynamically populated version selection to
 documentation

---
 doc/_templates/versions.html | 51 ++++++++++++++++++++++++++++++++++++
 doc/conf.py                  |  2 +-
 2 files changed, 52 insertions(+), 1 deletion(-)
 create mode 100644 doc/_templates/versions.html

diff --git a/doc/_templates/versions.html b/doc/_templates/versions.html
new file mode 100644
index 000000000..161c1b682
--- /dev/null
+++ b/doc/_templates/versions.html
@@ -0,0 +1,51 @@
+<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>
+        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 => {
+                // 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(/\/$/, ''));
+                    }
+                });
+
+                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>
diff --git a/doc/conf.py b/doc/conf.py
index afb0d83ec..188e70c6b 100644
--- a/doc/conf.py
+++ b/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.

From 9c242d7976e1c8510c01a142bb09ef136b3588c7 Mon Sep 17 00:00:00 2001
From: tmadlener <thomas.madlener@desy.de>
Date: Fri, 23 Aug 2024 20:55:34 +0200
Subject: [PATCH 5/7] Order available versions from newest to oldest

---
 doc/_templates/versions.html | 52 +++++++++++++++++++++++++++---------
 1 file changed, 40 insertions(+), 12 deletions(-)

diff --git a/doc/_templates/versions.html b/doc/_templates/versions.html
index 161c1b682..d03bcd181 100644
--- a/doc/_templates/versions.html
+++ b/doc/_templates/versions.html
@@ -9,6 +9,43 @@
     <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 = '';
 
@@ -18,18 +55,9 @@
         fetch(baseUrl)
             .then(response => response.text())
             .then(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(/\/$/, ''));
-                    }
-                });
+                const availableVersions = getAvailableVersions(contents);
+
+                availableVersions.sort(sortVersions);
 
                 const versionList = document.createElement("dl");
                 const header = document.createElement("dt");

From bea57c2f64b29b6ab75fcd728dfb1443fe841315 Mon Sep 17 00:00:00 2001
From: tmadlener <thomas.madlener@desy.de>
Date: Fri, 23 Aug 2024 20:59:51 +0200
Subject: [PATCH 6/7] Also trigger deployments on new tags

---
 .gitlab-ci.yml | 1 +
 1 file changed, 1 insertion(+)

diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
index f851e5596..7ffd2f2a4 100644
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
@@ -63,6 +63,7 @@ deployment:
     refs:
       - master
       - versioned-docs
+      - /^v\d+-\d+-?\d+?$/
   # need the doxygen artifacts for this step
   dependencies:
     - generate-docs

From db9a569dc7b6d8fda1ea9e3273d154f910fb3b33 Mon Sep 17 00:00:00 2001
From: tmadlener <thomas.madlener@desy.de>
Date: Fri, 23 Aug 2024 21:44:03 +0200
Subject: [PATCH 7/7] Add top level index.html and minimal conceptual README

---
 doc/web-deploy/README.md  | 28 ++++++++++++++++++++++++++++
 doc/web-deploy/index.html | 11 +++++++++++
 2 files changed, 39 insertions(+)
 create mode 100644 doc/web-deploy/README.md
 create mode 100644 doc/web-deploy/index.html

diff --git a/doc/web-deploy/README.md b/doc/web-deploy/README.md
new file mode 100644
index 000000000..e3a95bcc4
--- /dev/null
+++ b/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
diff --git a/doc/web-deploy/index.html b/doc/web-deploy/index.html
new file mode 100644
index 000000000..595178255
--- /dev/null
+++ b/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>
\ No newline at end of file