CI: verify docs up to date

.github/workflows/lint.yml

@@ -7,22 +7,47 @@ env:
   FORCE_COLOR: 1
 jobs:
   lint:
+    name: ${{ matrix.python-version }} / ${{ matrix.toxenv || "(other)" }}
+    timeout-minutes: 10
     name: tox-${{ matrix.toxenv }}
     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 }}
         uses: actions/setup-python@v5
         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