From cb6ab6473b8fe57d72ef90bc349f58e8dec8a1a1 Mon Sep 17 00:00:00 2001 From: igerber Date: Sun, 10 May 2026 14:17:26 -0400 Subject: [PATCH 1/4] 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/4] 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 From 51022b5bc8dec4fab05e48cc2df0fe5144b624bb Mon Sep 17 00:00:00 2001 From: igerber Date: Mon, 11 May 2026 17:22:42 -0400 Subject: [PATCH 3/4] Add ipython to docs deps so nbsphinx Pygments lexer resolves under -W MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit CI's new Sphinx HTML build (-W) failed with "Pygments lexer name 'ipython3' is not known [misc.highlighting_failure]" warnings on every .ipynb in docs/tutorials/. nbsphinx renders notebook code cells with the ipython3 lexer; that lexer ships with the IPython package and is not included in our docs extras. My local venv had IPython transitively (common dev dep), masking the gap. RTD has been emitting these warnings silently since it builds without -W. Added "ipython>=8.0" to all three sync'd surfaces: - pyproject.toml [project.optional-dependencies.docs] - .readthedocs.yaml post_install pip install - .github/workflows/docs-tests.yml sphinx-build job Verified locally with python3 -c "from pygments.lexers import get_lexer_by_name; print(get_lexer_by_name('ipython3'))" — returns when IPython is installed. Co-Authored-By: Claude Opus 4.7 (1M context) --- .github/workflows/docs-tests.yml | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/.github/workflows/docs-tests.yml b/.github/workflows/docs-tests.yml index 7c79549a..5d0bd082 100644 --- a/.github/workflows/docs-tests.yml +++ b/.github/workflows/docs-tests.yml @@ -92,7 +92,9 @@ jobs: # 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" + # 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. From ade6429f6bb552178fe89d998e11fccdb95cf0a7 Mon Sep 17 00:00:00 2001 From: igerber Date: Mon, 11 May 2026 17:23:07 -0400 Subject: [PATCH 4/4] Sync ipython>=8.0 into pyproject docs extras + .readthedocs.yaml Companion to commit 51022b5 which added ipython to the workflow only. Per the workflow comment "Keep in sync with pyproject.toml [project.optional-dependencies.docs] and .readthedocs.yaml post_install", add the same dep to the other two surfaces so RTD builds (which run without -W) also stop emitting silent highlighting_failure warnings on notebook code cells. Co-Authored-By: Claude Opus 4.7 (1M context) --- .readthedocs.yaml | 2 +- pyproject.toml | 4 ++++ 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 0b942854..3883234a 100644 --- 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/pyproject.toml b/pyproject.toml index 06fab28c..9d56376b 100644 --- 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]