From 966f26527b42123c27b017176194223e15eb0343 Mon Sep 17 00:00:00 2001
From: Damian Sowinski <drsowinski@gmail.com>
Date: Wed, 19 Aug 2026 02:38:57 -0400
Subject: [PATCH 1/4] Run the test suite and documentation build on GitHub for
 every push and pull request

---
 .github/workflows/tests.yml | 38 +++++++++++++++++++++++++++++++++++++
 1 file changed, 38 insertions(+)
 create mode 100644 .github/workflows/tests.yml

diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
new file mode 100644
index 0000000..16dea26
--- /dev/null
+++ b/.github/workflows/tests.yml
@@ -0,0 +1,38 @@
+name: tests
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install pyCE with the test extra
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e '.[test]'
+      - name: Run the test suite
+        run: python -m pytest
+
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install pyCE with the docs extra
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e '.[docs]'
+      - name: Build the manual
+        run: make -C docs html

From c9fee24675febdabbadacd740c62690e87154491 Mon Sep 17 00:00:00 2001
From: Damian Sowinski <drsowinski@gmail.com>
Date: Wed, 19 Aug 2026 02:44:31 -0400
Subject: [PATCH 2/4] no-mistakes(review): Restrict workflow token scope and
 fail docs build on warnings

---
 .github/workflows/tests.yml | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
index 16dea26..66ba649 100644
--- a/.github/workflows/tests.yml
+++ b/.github/workflows/tests.yml
@@ -4,6 +4,9 @@ on:
   push:
   pull_request:
 
+permissions:
+  contents: read
+
 jobs:
   test:
     runs-on: ubuntu-latest
@@ -35,4 +38,4 @@ jobs:
           python -m pip install --upgrade pip
           pip install -e '.[docs]'
       - name: Build the manual
-        run: make -C docs html
+        run: make -C docs html SPHINXOPTS=-W

From 0cd75015c5998c4303f4a4cd1392b47d12c6149a Mon Sep 17 00:00:00 2001
From: Damian Sowinski <drsowinski@gmail.com>
Date: Wed, 19 Aug 2026 02:58:21 -0400
Subject: [PATCH 3/4] no-mistakes(test): Stop unreachable intersphinx inventory
 failing docs build

---
 docs/conf.py | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)

diff --git a/docs/conf.py b/docs/conf.py
index 3a1fe47..24675d8 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -12,6 +12,7 @@
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
+import logging
 import os
 import sys
 sys.path.insert(0, os.path.abspath('.'))
@@ -215,6 +216,30 @@
 # Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {'python': ('https://docs.python.org/3', None)}
 
+
+class _IgnoreUnreachableInventories(logging.Filter):
+    """Drop intersphinx's warning about inventories it could not download.
+
+    The manual is built with warnings treated as errors, so without this a
+    network blip while fetching https://docs.python.org/3/objects.inv would
+    fail the build for reasons that have nothing to do with the documentation.
+    Sphinx logs that warning without a type, so ``suppress_warnings`` cannot
+    match it (see ``sphinx.util.logging.is_suppressed_warning``).  Only this
+    one message is dropped: a malformed ``intersphinx_mapping`` is logged as an
+    error and unresolved cross-references are reported separately, so both
+    still fail the build.
+    """
+
+    def filter(self, record):
+        return 'failed to reach any of the inventories' not in str(record.msg)
+
+
+def setup(app):
+    logging.getLogger('sphinx.sphinx.ext.intersphinx').addFilter(
+        _IgnoreUnreachableInventories()
+    )
+
+
 # -- Options for todo extension ----------------------------------------------
 
 # If true, `todo` and `todoList` produce output, else they produce nothing.

From c4cb74438f1a3fd278b3ccb434136cb10f2fbc30 Mon Sep 17 00:00:00 2001
From: Damian Sowinski <drsowinski@gmail.com>
Date: Wed, 19 Aug 2026 03:15:21 -0400
Subject: [PATCH 4/4] no-mistakes(document): Default docs Makefile to -W, drop
 CI's duplicate flag

---
 .github/workflows/tests.yml | 2 +-
 docs/Makefile               | 9 ++++++++-
 2 files changed, 9 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
index 66ba649..0c3c3bf 100644
--- a/.github/workflows/tests.yml
+++ b/.github/workflows/tests.yml
@@ -38,4 +38,4 @@ jobs:
           python -m pip install --upgrade pip
           pip install -e '.[docs]'
       - name: Build the manual
-        run: make -C docs html SPHINXOPTS=-W
+        run: make -C docs html
diff --git a/docs/Makefile b/docs/Makefile
index c697b11..7651f5e 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -2,7 +2,14 @@
 #
 
 # You can set these variables from the command line.
-SPHINXOPTS    =
+# -W turns Sphinx warnings into errors, so a stale toctree entry, a malformed
+# directive or a duplicate label fails the build instead of scrolling past.
+# (Unresolved Python cross-references stay silent unless -n is added too.)
+# It lives here rather than in the CI command so that the plain
+# `make -C docs html` published in the README behaves the same on a
+# contributor's machine as it does on GitHub.  `?=` keeps it overridable, e.g.
+# `SPHINXOPTS= make html` while drafting.
+SPHINXOPTS   ?= -W
 SPHINXBUILD   = sphinx-build
 SPHINXPROJ    = pyCE
 SOURCEDIR     = .