generate examples in ci on the fly

.github/workflows/docs.yml

@@ -10,17 +10,24 @@ on:
     - cron: '0 8 * * 1' # run every Monday at 8am UTC
 
 jobs:
+  setup:
+    runs-on: ubuntu-latest
+    outputs:
+      examplesmatrix: ${{ steps.collectExamples.outputs.examples }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - id: collectExamples
+        run: |
+          EXAMPLES=$(./developer/get_examples.py)
+          echo "examples=$(jq -cn --argjson env "$EXAMPLES" '{example-name: $env}')" >> $GITHUB_OUTPUT
+
   generate-example:
+    needs: setup
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        example-name:
-          - lode-linear
-          - roy-gch
-          - sample-selection
-          - gaas-map
-          - batch-cp2k
-          - lpr
+        ${{ fromJson(needs.setup.outputs.examplesmatrix) }}
 
     steps:
       - uses: actions/checkout@v4

developer/get_examples.py

@@ -0,0 +1,21 @@
+#!/usr/bin/env python3
+"""Script to create JSON array useful for a github action matrix."""
+import glob
+import json
+import os
+
+
+ROOT = os.path.realpath(os.path.join(os.path.dirname(__file__), ".."))
+EXAMPLES = os.path.join(ROOT, "examples")
+
+
+def get_examples():
+    """The current list of examples, determined from the directories on disk"""
+    return [
+        os.path.basename(os.path.normpath(file)) for file in glob.glob(f"{EXAMPLES}/*")
+    ]
+
+
+if __name__ == "__main__":
+    # no spaces between elements are allowed for using array in bash
+    print(json.dumps(get_examples(), separators=(',', ':')))

noxfile.py

@@ -2,10 +2,17 @@
 import hashlib
 import json
 import os
+import sys
 
 import nox
 
 
+ROOT = os.path.realpath(os.path.dirname(__file__))
+
+sys.path.append(ROOT)
+from developer.get_examples import get_examples  # noqa: E402
+
+
 # global nox options
 nox.needs_version = ">=2024"
 nox.options.reuse_venv = "yes"
@@ -19,12 +26,10 @@
     "noxfile.py",
     "docs/src/conf.py",
     "examples",
+    "developer",
 ]
 
-# the current list of examples, determined from the directories on disk
-EXAMPLES = [
-    os.path.basename(os.path.normpath(file)) for file in glob.glob("examples/*/")
-]
+EXAMPLES = get_examples()
 
 # ==================================================================================== #
 #                                 helper functions                                     #