Add documentation version switcher

upa-url · Oct 28, 2023 · 4325706 · 4325706
1 parent c988b2e
commit 4325706
Show file tree

Hide file tree

Showing 5 changed files with 92 additions and 2 deletions.
diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml
@@ -18,7 +18,18 @@ jobs:
       - name: Download theme
         run: doc/download-theme.sh
       - uses: mattnotmitt/doxygen-action@edge
-      - name: Deploy
+
+      - name: Deploy version switcher
+        uses: peaceiris/actions-gh-pages@v3
+        if: github.ref == 'refs/heads/main'
+        with:
+          deploy_key: ${{ secrets.ACTIONS_DEPLOY_KEY }}
+          external_repository: upa-url/docs
+          destination_dir: docs/common
+          publish_branch: main
+          publish_dir: ./doc/common
+
+      - name: Deploy documentation
         uses: peaceiris/actions-gh-pages@v3
         if: github.ref == 'refs/heads/main'
         with:

diff --git a/doc/common/version-select.css b/doc/common/version-select.css
@@ -0,0 +1,12 @@
+#version-td {
+  padding: 0 0 0 0.5em;
+}
+
+#version-select {
+  background-color: transparent;
+  border: none;
+  font-family: inherit;
+  font-size: inherit;
+  cursor: pointer;
+  line-height: inherit;
+}
diff --git a/doc/common/version-select.js b/doc/common/version-select.js
@@ -0,0 +1,59 @@
+// Copyright 2023 Rimas Misevičius
+// Distributed under the BSD-style license that can be
+// found in the LICENSE file.
+
+(function () {
+  // path segment to replace with version string
+  const path_segment_ind = 2;
+  // versions.txt is in the same folder as this script
+  const versions_url = new URL("versions.txt", document.currentScript.src);
+
+  window.addEventListener("DOMContentLoaded", event => {
+    const list_ctl = document.getElementById("version-select");
+
+    function on_change() {
+      const path_segments = window.location.pathname.split('/');
+      path_segments[path_segment_ind] = list_ctl.value;
+      list_ctl.value = initial_dir; // return version of this document
+      // ... and load document of other version
+      window.location.pathname = path_segments.join('/');
+    }
+
+    // Initial version
+    const initial_dir = window.location.pathname.split('/')[path_segment_ind];
+    const initial_option = list_ctl.options[0];
+    initial_option.selected = true;
+    initial_option.value = initial_dir;
+    // Change event
+    list_ctl.addEventListener("change", on_change);
+
+    // Fetch versions and populate versions list
+    fetch(versions_url)
+    .then(response => response.text())
+    .then(text => {
+      // Split text into lines and remove blank lines if present
+      const versions = text
+        .split(/\r?\n/gm)
+        .map(line => line.trim())
+        .filter(line => line.length > 0)
+        .map(line => line.split(":"));
+      // Populate versions list
+      let append = false;
+      versions.forEach(dir_ver => {
+        const dir = dir_ver[0];
+        const ver = dir_ver[dir_ver.length - 1];
+        if (dir === initial_dir) {
+          append = true;
+        } else {
+          const option = document.createElement('option');
+          option.text = ver;
+          option.value = dir;
+          if (append)
+            list_ctl.appendChild(option);
+          else
+            list_ctl.insertBefore(option, initial_option)
+        }
+      });
+    });
+  });
+})();
diff --git a/doc/common/versions.txt b/doc/common/versions.txt
@@ -0,0 +1 @@
+main
diff --git a/doc/header.html b/doc/header.html
@@ -23,13 +23,15 @@
 <script type="text/javascript" src="$relpath^doxygen-awesome-darkmode-toggle.js"></script>
 <script type="text/javascript" src="$relpath^doxygen-awesome-fragment-copy-button.js"></script>
 <script type="text/javascript" src="$relpath^doxygen-awesome-paragraph-link.js"></script>
+<script type="text/javascript" src="$relpath^../common/version-select.js"></script>
 <script type="text/javascript">
   DoxygenAwesomeDarkModeToggle.init()
   DoxygenAwesomeFragmentCopyButton.init()
   DoxygenAwesomeParagraphLink.init()
 </script>
 <link href="$relpath^$stylesheet" rel="stylesheet" type="text/css" />
 $extrastylesheet
+<link href="$relpath^../common/version-select.css" rel="stylesheet" type="text/css" />
 </head>
 <body>
 <!--BEGIN DISABLE_INDEX-->
@@ -50,10 +52,15 @@
   <!--END PROJECT_LOGO-->
   <!--BEGIN PROJECT_NAME-->
   <td id="projectalign">
-   <div id="projectname">$projectname<!--BEGIN PROJECT_NUMBER--><span id="projectnumber">&#160;$projectnumber</span><!--END PROJECT_NUMBER-->
+   <div id="projectname">$projectname
    </div>
    <!--BEGIN PROJECT_BRIEF--><div id="projectbrief">$projectbrief</div><!--END PROJECT_BRIEF-->
   </td>
+  <!--BEGIN PROJECT_NUMBER-->
+  <td id="version-td">
+   <select id="version-select"><option>$projectnumber</option></select>
+  </td>
+  <!--END PROJECT_NUMBER-->
   <!--END PROJECT_NAME-->
   <!--BEGIN !PROJECT_NAME-->
    <!--BEGIN PROJECT_BRIEF-->