From 357facf7a9859b9c77ffabd886bae7adef0b82de Mon Sep 17 00:00:00 2001 From: igerber Date: Thu, 14 May 2026 19:35:00 -0400 Subject: [PATCH 1/3] docs: shorten 3 top-nav labels + bump pydata-sphinx-theme floor Two independent low-risk nav cleanups: 1. Shorten 3 top-nav labels via toctree entry overrides in docs/index.rst. "Getting Started: Measuring Campaign Impact", "Which Analysis Method Fits Your Problem?", and "Choosing an Estimator" all wrap to 2 lines at 1440x900 desktop, doubling header height from ~64px to 128px (14% of viewport). Use Sphinx's `Label ` toctree syntax to render shorter labels in the nav while preserving each page's full H1 title: - Practitioner Guide (was: Getting Started: Measuring Campaign Impact) - Decision Tree (was: Which Analysis Method Fits Your Problem?) - Estimator Guide (was: Choosing an Estimator) Verified locally: header height drops from 128px to 64px; page H1s unchanged; mobile drawer entries 1, 2, 4 reflect the new labels. 2. Bump pydata-sphinx-theme floor >=0.15 -> >=0.16.1 across pyproject.toml, .readthedocs.yaml, and .github/workflows/docs-tests.yml. v0.16+ shipped accessibility improvements. RTD attribution shows 0.17.1 already deployed, but 0.16.1 is the highest floor we can land while keeping Python 3.9 compatibility (0.17.1 requires Python>=3.10, which would conflict with project's requires-python>=3.9). On Python 3.11 (RTD/CI) pip resolves to 0.17.1 as before; on Python 3.9 (local dev) 0.16.1 installs. Verified locally: `make html SPHINXOPTS="-W"` builds clean with pydata-sphinx-theme 0.16.1 installed. Co-Authored-By: Claude Opus 4.7 (1M context) --- .github/workflows/docs-tests.yml | 2 +- .readthedocs.yaml | 2 +- docs/index.rst | 6 +++--- pyproject.toml | 2 +- 4 files changed, 6 insertions(+), 6 deletions(-) diff --git a/.github/workflows/docs-tests.yml b/.github/workflows/docs-tests.yml index 5d0bd082d..1939fb1d4 100644 --- a/.github/workflows/docs-tests.yml +++ b/.github/workflows/docs-tests.yml @@ -94,7 +94,7 @@ jobs: # 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" + run: pip install "numpy>=1.20.0" "pandas>=1.3.0" "scipy>=1.7.0" "sphinx>=6.0" "pydata-sphinx-theme>=0.16.1" "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. diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 3883234a9..b4f2c3c00 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" "ipython>=8.0" + - pip install "numpy>=1.20.0" "pandas>=1.3.0" "scipy>=1.7.0" "sphinx>=6.0" "pydata-sphinx-theme>=0.16.1" "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 index b1b8721f4..ea7f8ad05 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -59,8 +59,8 @@ Quick Links :caption: For Data Scientists :hidden: - practitioner_getting_started - practitioner_decision_tree + Practitioner Guide + Decision Tree .. toctree:: :maxdepth: 2 @@ -68,7 +68,7 @@ Quick Links :hidden: quickstart - choosing_estimator + Estimator Guide troubleshooting references diff --git a/pyproject.toml b/pyproject.toml index 9d56376b0..93666428d 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -68,7 +68,7 @@ plotly = [ ] docs = [ "sphinx>=6.0", - "pydata-sphinx-theme>=0.15", + "pydata-sphinx-theme>=0.16.1", "sphinxext-opengraph>=0.9", "sphinx-sitemap>=2.5", "nbsphinx>=0.9", From 4ff5dad1ebc61357027e5ab7d7e9516ab922dc11 Mon Sep 17 00:00:00 2001 From: igerber Date: Thu, 14 May 2026 20:15:00 -0400 Subject: [PATCH 2/3] ci: add Python 3.9 docs-deps install smoke job The existing sphinx-build job runs on Python 3.11 to mirror RTD. This new job runs the same pip install line on Python 3.9 to validate the docs dependency floor against the project's declared minimum Python (pyproject.toml requires-python>=3.9). Catches drift where a docs dep upgrade silently requires a newer Python than the project advertises - exactly the constraint that drove the previous commit's choice of pydata-sphinx-theme>=0.16.1 (vs 0.17.1, which requires Python>=3.10). The job only installs deps. Full Sphinx build remains exclusively on the 3.11 sphinx-build job; this is a fast install-only smoke (~30s). Co-Authored-By: Claude Opus 4.7 (1M context) --- .github/workflows/docs-tests.yml | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/.github/workflows/docs-tests.yml b/.github/workflows/docs-tests.yml index 1939fb1d4..378fbdc50 100644 --- a/.github/workflows/docs-tests.yml +++ b/.github/workflows/docs-tests.yml @@ -101,3 +101,34 @@ jobs: # 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-deps-py39-smoke: + name: Validate docs deps install on Python 3.9 (floor compat) + 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: Set up Python 3.9 + uses: actions/setup-python@v6 + with: + # 3.9 is the project's declared floor (pyproject.toml requires-python + # >=3.9). The sphinx-build job above runs on 3.11; this job verifies + # the docs dependency set actually installs on the floor Python so + # we catch drift like pydata-sphinx-theme>=0.17.1 (which requires + # Python>=3.10) before it lands. + python-version: '3.9' + + - name: Install docs dependencies + # Same pip install line as sphinx-build above. Just installs - does + # not run a Sphinx build (sphinx-build covers full rendering on 3.11). + # Failure here means the docs floor declared in pyproject.toml / + # .readthedocs.yaml / above is not installable on Python 3.9. + run: pip install "numpy>=1.20.0" "pandas>=1.3.0" "scipy>=1.7.0" "sphinx>=6.0" "pydata-sphinx-theme>=0.16.1" "sphinxext-opengraph>=0.9" "sphinx-sitemap>=2.5" "nbsphinx>=0.9" "matplotlib>=3.5" "ipython>=8.0" + + - name: Confirm pydata-sphinx-theme version + # Surface the resolved version in the log for future debugging. + run: pip show pydata-sphinx-theme | head -3 From e85ec4906bb384758b746cf20fa48c7184e1ac08 Mon Sep 17 00:00:00 2001 From: igerber Date: Thu, 14 May 2026 20:20:32 -0400 Subject: [PATCH 3/3] ci: replace pipefail-unsafe pip-show|head with importlib.metadata The previous `pip show pydata-sphinx-theme | head -3` would SIGPIPE under bash -o pipefail (GitHub Actions default): head closes the pipe after 3 lines, pip show exits non-zero, the step fails despite a successful install. Replace with a single Python invocation against importlib.metadata that prints just the resolved version. No pipe involved, no broken exit codes, and the output is what we actually wanted to log. Verified locally: exit 0, prints `pydata-sphinx-theme 0.16.1`. Co-Authored-By: Claude Opus 4.7 (1M context) --- .github/workflows/docs-tests.yml | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/.github/workflows/docs-tests.yml b/.github/workflows/docs-tests.yml index 378fbdc50..129216705 100644 --- a/.github/workflows/docs-tests.yml +++ b/.github/workflows/docs-tests.yml @@ -131,4 +131,7 @@ jobs: - name: Confirm pydata-sphinx-theme version # Surface the resolved version in the log for future debugging. - run: pip show pydata-sphinx-theme | head -3 + # Avoid `pip show ... | head -3`: `head` closes the pipe after 3 + # lines and `pip show` exits non-zero under bash -o pipefail + # (GitHub Actions default), failing the step despite a clean install. + run: python -c "import importlib.metadata as m; print('pydata-sphinx-theme', m.version('pydata-sphinx-theme'))"