Merge pull request #1306 from UncleGrumpy/fix_docs_workflows

Fix documentation workflow caches

The Doxygen install cache needs to be kept in sync with the runner image used
for the workflow, otherwise builds may unexpectedly fail. This will prevent
future updates to the runner image from using an out of sync Doygen install
cache.

These changes are made under both the "Apache 2.0" and the "GNU Lesser General
Public License 2.1 or later" license terms (dual license).

SPDX-License-Identifier: Apache-2.0 OR LGPL-2.1-or-later

.github/workflows/build-docs.yaml

@@ -44,14 +44,20 @@ concurrency:
 jobs:
   # This workflow contains a single job called "build"
   build:
+
+    strategy:
+      fail-fast: false
+      ## don't add more than one OS to matrix, this is only to retrieve the full os-name for keeping cache in sync
+      matrix:
+        os: [ ubuntu-24.04 ]
     # The type of runner that the job will run on
-    runs-on: ubuntu-24.04
+    runs-on: ${{ matrix.os }}
+    # Documentation currently fails to build with OTP-27
     container: erlang:26
 
     # Steps represent a sequence of tasks that will be executed as part of the job
     steps:
       # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
-
       - name: Install Deps
         run: |
           apt update -y
@@ -61,7 +67,7 @@ jobs:
         id: sphinx-cache
         with:
           path: /home/runner/python-env/sphinx
-          key: ${{ runner.os }}-sphinx-install
+          key: ${{ matrix.os }}-${{ job.container.id }}-sphinx-install
 
       - name: Install Sphinx
         if: ${{ steps.sphinx-cache.outputs.cache-hit != 'true' }}
@@ -100,6 +106,7 @@ jobs:
           done
 
       - name: Build Site
+        id: build
         shell: bash
         run: |
           . /home/runner/python-env/sphinx/bin/activate

.github/workflows/publish-docs.yaml

@@ -31,15 +31,19 @@ concurrency:
   group: ${{ github.workflow }}-${{  github.ref_name }}
   cancel-in-progress: true
 
+env:
+  AVM_DOCS_NAME: ${{ github.ref_name }}
+
 # A workflow run is made up of one or more jobs that can run sequentially or in parallel
 jobs:
   # This workflow contains a single job called "build"
   build:
+    strategy:
+      ## don't add more than one OS to matrix, this is only to retrieve the full os-name for keeping cache in sync
+      matrix:
+        os: [ ubuntu-24.04 ]
     # The type of runner that the job will run on
-    runs-on: ubuntu-24.04
-
-    env:
-      AVM_DOCS_NAME: ${{ github.ref_name }}
+    runs-on: ${{ matrix.os }}
 
     # Steps represent a sequence of tasks that will be executed as part of the job
     steps:
@@ -54,7 +58,7 @@ jobs:
         id: sphinx-cache
         with:
           path: /home/runner/python-env/sphinx
-          key: ${{ runner.os }}-sphinx-install
+          key: ${{ matrix.os }}-sphinx-install
 
       - name: Install Sphinx
         if: ${{ steps.sphinx-cache.outputs.cache-hit != 'true' }}