igerber · igerber · May 11, 2026 · May 10, 2026 · May 10, 2026 · May 11, 2026
diff --git a/.github/workflows/docs-tests.yml b/.github/workflows/docs-tests.yml
@@ -13,6 +13,9 @@ on:
       # file itself.
       - 'tests/conftest.py'
       - 'pyproject.toml'
+      # sphinx-build job mirrors RTD setup; trigger when RTD config drifts
+      # (Python version, apt packages, post_install docs deps).
+      - '.readthedocs.yaml'
       - '.github/workflows/docs-tests.yml'
   pull_request:
     branches: [main]
@@ -23,6 +26,9 @@ on:
       - 'tests/test_doc_snippets.py'
       - 'tests/conftest.py'
       - 'pyproject.toml'
+      # sphinx-build job mirrors RTD setup; trigger when RTD config drifts
+      # (Python version, apt packages, post_install docs deps).
+      - '.readthedocs.yaml'
       - '.github/workflows/docs-tests.yml'
   schedule:
     # Weekly Sunday 6am UTC - smoke test that snippets still execute
@@ -60,3 +66,38 @@ jobs:
         # source without invoking the maturin/Rust build (mirrors Pure
         # Python Fallback at rust-test.yml:189-193).
         run: PYTHONPATH=. DIFF_DIFF_BACKEND=python pytest tests/test_doc_snippets.py -v
+
+  sphinx-build:
+    name: Sphinx HTML build (-W warnings as errors)
+    if: >-
+      github.event_name != 'pull_request'
+      || contains(github.event.pull_request.labels.*.name, 'ready-for-ci')
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install pandoc
+        # nbsphinx invokes pandoc to render notebook markdown cells.
+        run: sudo apt-get update && sudo apt-get install -y pandoc
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          # Match the RTD build (.readthedocs.yaml:9) so CI catches drift
+          # against what users actually see on diff-diff.readthedocs.io.
+          python-version: '3.11'
+
+      - name: Install docs dependencies
+        # Keep in sync with pyproject.toml [project.optional-dependencies.docs]
+        # and .readthedocs.yaml post_install. Skips the maturin/Rust build:
+        # docs/conf.py imports diff_diff via sys.path from checked-out source.
+        # ipython provides the 'ipython3' Pygments lexer that nbsphinx uses
+        # for notebook code cells; without it -W fires highlighting_failure.
+        run: pip install "numpy>=1.20.0" "pandas>=1.3.0" "scipy>=1.7.0" "sphinx>=6.0" "pydata-sphinx-theme>=0.15" "sphinxext-opengraph>=0.9" "sphinx-sitemap>=2.5" "nbsphinx>=0.9" "matplotlib>=3.5" "ipython>=8.0"
+
+      - name: Build docs with warnings as errors
+        # SPHINXOPTS="-W" turns every Sphinx warning into a build failure.
+        # PR #410 brought make html to 0 warnings; -W keeps it that way by
+        # blocking any new warning from sneaking in.
+        run: make -C docs html SPHINXOPTS="-W"
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
@@ -18,7 +18,7 @@ build:
       #
       # Keep in sync with pyproject.toml [project.dependencies]
       # and [project.optional-dependencies.docs].
-      - pip install "numpy>=1.20.0" "pandas>=1.3.0" "scipy>=1.7.0" "sphinx>=6.0" "pydata-sphinx-theme>=0.15" "sphinxext-opengraph>=0.9" "sphinx-sitemap>=2.5" "nbsphinx>=0.9" "matplotlib>=3.5"
+      - pip install "numpy>=1.20.0" "pandas>=1.3.0" "scipy>=1.7.0" "sphinx>=6.0" "pydata-sphinx-theme>=0.15" "sphinxext-opengraph>=0.9" "sphinx-sitemap>=2.5" "nbsphinx>=0.9" "matplotlib>=3.5" "ipython>=8.0"
 
 # Build documentation in the "docs/" directory with Sphinx
 sphinx:

diff --git a/docs/index.rst b/docs/index.rst
@@ -81,6 +81,7 @@ Quick Links
    tutorials/18_geo_experiments
    tutorials/19_dcdh_marketing_pulse
    tutorials/20_had_brand_campaign
+   tutorials/21_had_pretest_workflow
 
 .. toctree::
    :maxdepth: 1

diff --git a/pyproject.toml b/pyproject.toml
@@ -73,6 +73,10 @@ docs = [
     "sphinx-sitemap>=2.5",
     "nbsphinx>=0.9",
     "matplotlib>=3.5",
+    # ipython provides the 'ipython3' Pygments lexer used by nbsphinx for
+    # notebook code cells; without it Sphinx emits highlighting_failure
+    # warnings on every notebook.
+    "ipython>=8.0",
 ]
 
 [project.urls]