CI: verify docs up to date

.github/workflows/lint.yml

@@ -14,15 +14,38 @@ jobs:
       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