From accfab303202ced951c89f16f75ef0ec05f76af2 Mon Sep 17 00:00:00 2001
From: "Paul J. Dorn" <pajod@users.noreply.github.com>
Date: Wed, 22 May 2024 05:39:54 +0200
Subject: [PATCH] CI: verify docs up to date

---
 .github/workflows/lint.yml | 28 ++++++++++++++++++++++++++--
 1 file changed, 26 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml
index b0a862cd1..c144d8c74 100644
--- a/.github/workflows/lint.yml
+++ b/.github/workflows/lint.yml
@@ -7,13 +7,18 @@ env:
   FORCE_COLOR: 1
 jobs:
   lint:
-    name: tox-${{ matrix.toxenv }}
+    name: ${{ matrix.python-version }} / tox-${{ matrix.toxenv || "(other)" }}
+    timeout-minutes: 10
     runs-on: ubuntu-latest
     strategy:
       fail-fast: false
       matrix:
         toxenv: [lint, docs-lint, pycodestyle]
         python-version: [ "3.10" ]
+        include:
+          # for actions that want git env, not tox env
+          - toxenv: null
+            python-version: "3.10"
     steps:
       - uses: actions/checkout@v4
       - name: Using Python ${{ matrix.python-version }}
@@ -21,8 +26,27 @@ jobs:
         with:
           python-version: ${{ matrix.python-version }}
           cache: pip
-      - name: Install Dependencies
+      - name: Install Dependencies (tox)
+        if: ${{ matrix.toxenv }}
         run: |
           python -m pip install --upgrade pip
           python -m pip install tox
       - run: tox -e ${{ matrix.toxenv }}
+        if: ${{ matrix.toxenv }}
+      - name: Install Dependencies (non-toxic)
+        if: ${{ ! matrix.toxenv }}
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install tox
+      - name: "Update docs"
+        if: ${{ ! matrix.toxenv }}
+        run: |
+          # this will update docs/source/settings.rst - but will not create html output
+          (cd docs && sphinx-build -b "dummy" -d _build/doctrees source "_build/dummy")
+          if unclean=$(git status --untracked-files=no --porcelain) && [ -z "$unclean" ]; then
+            echo "no uncommitted changes in working tree (as it should be)"
+          else
+            echo "did you forget to run `make -C docs html`?"
+            echo "$unclean"
+            exit 2
+          fi