Added simple implementation of versioned Doxygen docs. Close #7

saxbophone · saxbophone · commit 10820d2b8cf1 · 2021-09-16T18:37:55.000+01:00
THE FOLLOWING PREREQUISITES/ASSUMPTIONS ARE REQUIRED FOR THIS FEATURE TO WORK:
- all release tags need to be of the form "vN.N.N" where N is a number (semantic versioning)
- project should observe semantic versioning requirements for API changes, as docs are only generated for _minor_ versions, i.e. the docs for latest patch release 1.2.3 will overwrite the docs for patch version 1.2.2, being placed under the /v1.2/ docs subdirectory
- the assumption is made that users accessing the docs from the site root want to be redirected to the latest version docs. There isn't a menu for browsing different versions of the docs, but one can manually change the URL to access docs for a given version that are known to exist.
- docs for old minor versions are not deleted, only updated when new patch versions for them are released. This means that if a large number of minor versions are iterated over, the github-pages branch will become quite full! However, one can always manually delete the folders for old minor versions that are no longer needed.
diff --git a/.github/workflows/build-release.yml b/.github/workflows/build-release.yml
@@ -5,7 +5,7 @@ on:
     types: [published]
 
 jobs:
-  build:
+  build-release:
     runs-on: ${{ matrix.os }}
     env:
       BUILD_TYPE: Release
@@ -57,3 +57,33 @@ jobs:
         with:
           name: project_build_${{ github.run_number }}_${{ matrix.platform_name }}
           path: ${{github.workspace}}/artifacts
+  build-docs:
+    runs-on: ubuntu-20.04
+    # don't deploy docs unless release build succeeds
+    needs: build-release
+    steps:
+      - uses: actions/checkout@v2
+      - 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.3
+      - name: Set up latest docs auto-linking
+        shell: bash
+        working-directory: ${{github.workspace}}
+        # make docs folder, move docs there, call script to generate HTML redirect in index
+        run: |
+          mkdir docs
+          cp -R 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: docs
+          clean: false
diff --git a/.github/workflows/continuous-integration.yml b/.github/workflows/continuous-integration.yml
@@ -8,7 +8,14 @@ on:
     types: [opened, synchronize]
 
 jobs:
-  build:
+  test-docs-build:
+    runs-on: ubuntu-20.04
+    steps:
+      - uses: actions/checkout@v2
+      - name: Build Doxygen Docs
+        uses: mattnotmitt/doxygen-action@v1.3.3
+
+  continuous-integration:
     runs-on: ${{ matrix.os }}
     env:
       BUILD_TYPE: Debug
diff --git a/Doxyfile b/Doxyfile
@@ -38,7 +38,7 @@ PROJECT_NAME           = "C++20 Cross Platform Template"
 # could be handy for archiving the generated documentation or if some version
 # control system is used.
 
-PROJECT_NUMBER         =
+PROJECT_NUMBER         = $(TAG_NAME)
 
 # Using the PROJECT_BRIEF tag one can provide an optional one line description
 # for a project that appears at the top of each page and should give viewer a
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";
