Copy documentation builder workflow from hpcflow

Author: dkfellows

.github/problem-matchers/sphinx.json

@@ -0,0 +1,40 @@
+{
+    "problemMatcher": [
+        {
+            "owner": "sphinx-problem-matcher",
+            "pattern": [
+                {
+                    "regexp": "^(.*):(\\d+):\\s+(\\w*):\\s+(.*)$",
+                    "file": 1,
+                    "line": 2,
+                    "severity": 3,
+                    "message": 4
+                }
+            ]
+        },
+        {
+            "owner": "sphinx-problem-matcher-loose",
+            "pattern": [
+                {
+                    "_comment": "A bit of a looser pattern, doesn't look for line numbers, just looks for file names relying on them to start with / and end with .rst",
+                    "regexp": "(\/.*\\.rst):\\s+(\\w*):\\s+(.*)$",
+                    "file": 1,
+                    "severity": 2,
+                    "message": 3
+                }
+            ]
+        },
+        {
+            "owner": "sphinx-problem-matcher-loose-no-severity",
+            "pattern": [
+                {
+                    "_comment": "Looks for file names ending with .rst and line numbers but without severity",
+                    "regexp": "^(.*\\.rst):(\\d+):(.*)$",
+                    "file": 1,
+                    "line": 2,
+                    "message": 3
+                }
+            ]           
+        }
+    ]
+}

.github/workflows/doc-build.yml

@@ -0,0 +1,45 @@
+name: Documentation
+run-name: doc
+env:
+  PYTHON_VERSION: "3.12"
+  POETRY_VERSION: "1.4"
+on: push
+jobs:
+  sphinx:
+    # Note that we only do this on one platform and with one Python version
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Init Python ${{ env.PYTHON_VERSION }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+      - name: Init Poetry ${{ env.POETRY_VERSION }}
+        run: |
+          python -m pip install poetry==${{ env.POETRY_VERSION }}
+          poetry config virtualenvs.in-project true
+          poetry config installer.modern-installation false
+      - name: Cache Virtual Environment
+        uses: actions/cache@v4
+        with:
+          path: ./.venv
+          key: ${{ runner.os }}-sphinx-${{ env.PYTHON_VERSION }}-venv-${{ hashFiles('**/poetry.lock') }}
+      - name: Install Dependencies
+        run: |
+          poetry install --without dev,pyinstaller
+      - name: Configure Problem Matcher
+        run: echo "::add-matcher::.github/problem-matchers/sphinx.json"
+        # See: https://github.com/actions/toolkit/blob/main/docs/problem-matchers.md
+        # See: https://github.com/python/cpython/pull/20325
+      - name: Run Sphinx
+        run: |
+          poetry run make clean html
+        working-directory: docs
+      - name: Upload documentation artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: matflow-documentation (${{ github.sha }})
+          path: docs/build/html
+          if-no-files-found: error
+  # TODO: Publish the docs to an internal site