From cb6ab6473b8fe57d72ef90bc349f58e8dec8a1a1 Mon Sep 17 00:00:00 2001 From: igerber Date: Sun, 10 May 2026 14:17:26 -0400 Subject: [PATCH 1/2] 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) --- .github/workflows/docs-tests.yml | 33 ++++++++++++++++++++++++++++++++ docs/index.rst | 1 + 2 files changed, 34 insertions(+) diff --git a/.github/workflows/docs-tests.yml b/.github/workflows/docs-tests.yml index 1b78e877..db04951f 100644 --- a/.github/workflows/docs-tests.yml +++ b/.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" diff --git a/docs/index.rst b/docs/index.rst index 4f1435d4..b1b8721f 100644 --- 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 From 86cc916b21f7a48d2307765bb5f2289fc05d399a Mon Sep 17 00:00:00 2001 From: igerber Date: Sun, 10 May 2026 14:28:38 -0400 Subject: [PATCH 2/2] Address PR #413 R1 P2: include .readthedocs.yaml in workflow path filters Reviewer caught that the new sphinx-build job mirrors .readthedocs.yaml (Python version, pandoc apt package, post_install docs deps) but the workflow's path filters omitted .readthedocs.yaml. A future PR changing only RTD config (e.g., Python version bump or new apt package) would skip this docs-build guard, allowing drift between CI's mirror and what RTD actually does. Added '.readthedocs.yaml' to both push.paths and pull_request.paths. Co-Authored-By: Claude Opus 4.7 (1M context) --- .github/workflows/docs-tests.yml | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/.github/workflows/docs-tests.yml b/.github/workflows/docs-tests.yml index db04951f..7c79549a 100644 --- 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