Merge pull request #8 from saxbophone/josh/7-multiversion-docs

saxbophone · web-flow · commit bfa998221a8d · 2021-09-16T18:54:41.000+01:00
Added simple implementation of versioned Doxygen docs. Close #7
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";
diff --git a/project/include/project/Public.hpp b/project/include/project/Public.hpp
@@ -2,7 +2,7 @@
  * @file
  * This is a sample public compilation unit.
  *
- * @author Your Name <your email address>
+ * @author Your Name <your.email.address@goes.here>
  * @date Creation/Edit Date
  *
  * @copyright Copyright information goes here
diff --git a/project/src/Private.cpp b/project/src/Private.cpp
@@ -1,4 +1,4 @@
-/**
+/*
  * This is a sample private compilation unit.
  *
  * <Copyright information goes here>
diff --git a/project/src/Private.hpp b/project/src/Private.hpp
@@ -1,4 +1,4 @@
-/**
+/*
  * This is a sample private compilation unit.
  *
  * <Copyright information goes here>
diff --git a/project/src/Public.cpp b/project/src/Public.cpp
@@ -1,4 +1,4 @@
-/**
+/*
  * This is a sample source file corresponding to a public header file.
  *
  * <Copyright information goes here>

Original file line number	Diff line number	Diff line change
`@@ -2,7 +2,7 @@`
`2`	`2`	`* @file`
`3`	`3`	`* This is a sample public compilation unit.`
`4`	`4`	`*`
`5`		`- * @author Your Name <your email address>`
	`5`	`+ * @author Your Name <your.email.address@goes.here>`
`6`	`6`	`* @date Creation/Edit Date`
`7`	`7`	`*`
`8`	`8`	`* @copyright Copyright information goes here`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-/**`
	`1`	`+/*`
`2`	`2`	`* This is a sample private compilation unit.`
`3`	`3`	`*`
`4`	`4`	`* <Copyright information goes here>`