prevent this workflow from running on branches besides main and dev

Author: tipatterson-dev

.github/workflows/docs_pages.yaml

@@ -1,5 +1,8 @@
 name: Docs2Pages
-on: [ push, pull_request, workflow_dispatch ]
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
 
 permissions: {}
 

.github/workflows/publish.yml

@@ -1,8 +1,9 @@
 name: Publish (PyPI)
 
 # Publishes any tag starting with 'v' (e.g. v1.0, v0.5.1a0) to PyPI via OIDC
-# trusted publishing. The publish job is gated on the full pytest matrix
-# passing on the tagged commit — we don't ship a release that fails CI.
+# trusted publishing. The publish job is gated on the full pytest matrix AND
+# the strict Sphinx build passing on the tagged commit — we don't ship a
+# release that fails CI or has broken docs.
 on:
   push:
     tags:
@@ -42,8 +43,30 @@ jobs:
         run: |
           uv run --python ${{ matrix.python-version }} pytest -v -m "not network"
 
+  # Strict Sphinx build — same gate `tests.yaml` runs on every dev push.
+  # A release deserves the same docstring/signature drift check.
+  docs:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+
+      - name: Install Python 3.13
+        run: uv python install 3.13
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+
+      - name: Build Sphinx + Furo site (strict)
+        run: uv run sphinx-build -W --keep-going -b html docs/source docs/build/sphinx
+
   publish:
-    needs: tests
+    needs: [tests, docs]
     runs-on: ubuntu-latest
     environment:
       name: publish

.github/workflows/tests.yaml

@@ -5,14 +5,14 @@ on:
     # before publishing — skip here to avoid running the suite twice.
     tags-ignore:
       - '**'
+    # `docs/**` is intentionally NOT ignored: docs-only commits still need
+    # to validate via the strict Sphinx build (the `docs` job below).
     paths-ignore:
-      - 'docs/**'
       - 'README.md'
       - 'CLAUDE.md'
       - '.github/workflows/docs_pages.yaml'
   pull_request:
     paths-ignore:
-      - 'docs/**'
       - 'README.md'
       - 'CLAUDE.md'
       - '.github/workflows/docs_pages.yaml'
@@ -67,11 +67,47 @@ jobs:
           if-no-files-found: warn
           retention-days: 7
 
+  # Strict Sphinx build acts as a docstring/signature drift gate. Runs in
+  # parallel with pytest; publish-test depends on both. Same `-W` flag the
+  # Pages deploy uses (docs_pages.yaml), so any failure here would also
+  # break the production deploy on main. The built site is uploaded as a
+  # workflow artifact so dev-branch docs changes can be previewed without
+  # deploying to GitHub Pages (which only happens from main).
+  docs:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+
+      - name: Install Python 3.13
+        run: uv python install 3.13
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+
+      - name: Build Sphinx + Furo site (strict)
+        run: uv run sphinx-build -W --keep-going -b html docs/source docs/build/sphinx
+
+      - name: Upload built docs as artifact
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: docs-html
+          path: docs/build/sphinx
+          if-no-files-found: warn
+          retention-days: 14
+
   # Publish a `.devN` pre-release wheel to TestPyPI on every push to dev,
-  # gated on the full pytest matrix passing. Lives in this workflow (rather
-  # than a separate `workflow_run`-triggered file) so that the gate is a
-  # plain `needs:` dependency — `workflow_run` only fires from workflows
-  # that exist on the default branch, which is a maintenance footgun.
+  # gated on BOTH the full pytest matrix and the strict docs build passing.
+  # Lives in this workflow (rather than a separate `workflow_run`-triggered
+  # file) so that the gate is a plain `needs:` dependency — `workflow_run`
+  # only fires from workflows that exist on the default branch, which is a
+  # maintenance footgun.
   #
   # One-time setup required at https://test.pypi.org/manage/account/publishing/
   #   Owner: Botts-Innovative-Research
@@ -80,7 +116,7 @@ jobs:
   #   Environment: publish-test
   # And in this repo's Settings -> Environments, create env `publish-test`.
   publish-test:
-    needs: pytest
+    needs: [pytest, docs]
     if: github.event_name == 'push' && github.ref == 'refs/heads/dev'
     runs-on: ubuntu-latest
     environment: