ci: run the test suite and docs build on every push and pull request

.github/workflows/tests.yml

@@ -0,0 +1,41 @@
+name: tests
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+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

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     = .

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.