docs: enforce Sphinx -W in CI (Sphinx cleanup PR 3)

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