Special setup to allow mutliversion docs with the latest one shown by default

saxbophone · saxbophone · commit f95f1951074c · 2021-05-05T03:29:25.000+01:00
It works by placing a tiny index HTML fragment at the site root, which just links to the latest docs.
Readers can tweak the URL to point to a previous version of the docs if they need to. Not ideal, but workable.
Also, we now only refer to docs URLs by the major and minor version numbers, we ignore patch versions. This should mean that for any given minor version, the latest patch version to be released is the one which that minor version URL will provide.
diff --git a/.github/workflows/build-release.yml b/.github/workflows/build-release.yml
@@ -63,15 +63,27 @@ jobs:
     needs: build-release
     steps:
       - uses: actions/checkout@v2
-      - name: Set Tag / Branch Name
+      - name: Set Tag Name
         shell: bash
+        # trim prefix from ref to get tag name
         run: echo "TAG_NAME=${GITHUB_REF#'refs/tags/'}" >> $GITHUB_ENV
+      - name: Format Docs Version Name
+        shell: bash
+        # trim patch version off version number as minor version specifies ABI changes
+        run: echo "DOCS_VERSION=${TAG_NAME%.*}" >> $GITHUB_ENV
       - name: Build Doxygen Docs
         uses: mattnotmitt/doxygen-action@v1.3.1
+      - name: Set up latest docs auto-linking
+        shell: bash
+        # make docs folder, move docs there, call script to generate HTML redirect in index
+        run: |
+          mkdir docs
+          mv html docs/$DOCS_VERSION
+          ./generate_index $DOCS_VERSION
       - name: Deploy Docs to github-pages
         uses: JamesIves/github-pages-deploy-action@4.1.1
         with:
           branch: gh-pages
           folder: html
-          target-folder: ${{env.TAG_NAME}}
+          target-folder: ${{env.DOCS_VERSION}}
           clean: false
diff --git a/generate_index b/generate_index
@@ -0,0 +1,16 @@
+#!/usr/bin/env bash
+
+# This script generates a tiny HTML file whose sole purpose is to
+# redirect to whichever folder the latest version of the docs is in
+#
+# This keeps things fairly simple, if a little clunky, as Github Pages
+# is a static site hosting service only (unless you're using Jekyll)
+# and Doxygen didn't support multi-version documentation sites at the
+# time of writing.
+
+# pass version string for where the latest docs are as single parameter
+DOCS_VERSION=$1;
+# HTML template with DOCS_VERSION substituted
+HTML_FRAGMENT="<head><meta http-equiv='refresh' content='0; URL=${DOCS_VERSION}/'/></head><body><p>If you are not redirected in five seconds,<a href='${DOCS_VERSION}/'>click here</a>.</p></body>";
+# write out to the index HTML file that will appear at the root of Github Pages
+echo $HTML_FRAGMENT > "docs/index.html";
