docs: enforce Sphinx -W in CI + add T21 to toctree (Sphinx PR 3)

Adds a sphinx-build job to .github/workflows/docs-tests.yml that runs
make -C docs html SPHINXOPTS="-W" so warnings become build failures.
This locks in the 0-warning state PR #410 achieved and blocks any
future warning from sneaking in.

The job mirrors the RTD build (.readthedocs.yaml): Python 3.11, pandoc
apt package for nbsphinx, and the same docs extras pinned in
pyproject.toml [project.optional-dependencies.docs].

Also adds tutorials/21_had_pretest_workflow to the Tutorials: Business
Applications toctree at docs/index.rst:84. PR #409 landed this notebook
without a toctree entry; -W enforcement caught it on the local smoke
test before push.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: igerber

.github/workflows/docs-tests.yml

@@ -60,3 +60,36 @@ 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.
+        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"
+
+      - 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"

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