FIX: Use alabaster in the gated test root to unbreak CI - #88
Merged
Conversation
The `gateddirective` test root was the only HTML test root using a third-party
theme (`html_theme = "sphinx_book_theme"`), which pulls in pydata-sphinx-theme.
Current pydata-sphinx-theme calls `_get_toctree_ancestors`, which does not exist
in Sphinx 6 or 7, so every HTML test using that root fails with:
sphinx.errors.ThemeError: An error happened in rendering the page exercise.
Reason: ImportError("cannot import name '_get_toctree_ancestors' from
'sphinx.environment.adapters.toctree'")
This is dependency drift rather than a code regression: main last ran CI on
2025-11-17, before the theme released the change, and nothing in this repo
changed. Six tests fail on the Sphinx 6 and 7 jobs.
The theme is incidental to what these tests check. The regression fixtures
capture only the `div.exercise` / `div.solution` markup this extension
generates, so no third-party theme is needed to exercise them, and depending on
one couples the suite to that theme's Sphinx support matrix. The other three
HTML test roots already use alabaster; this brings the fourth into line.
Pinning the theme instead was considered and rejected: it would need a
per-Sphinx-version pin and would rot again on the next release, whereas
removing the dependency from the HTML test path ends the whole class of
failure.
`test-simplebook` still names sphinx_book_theme but is only ever built with the
latex builder, which never loads an HTML theme, so it is unaffected and left
alone.
Verified by reproducing the exact CI combination locally (Python 3.13,
Sphinx 6.2.1, pydata-sphinx-theme 0.20.0, sphinx-book-theme 1.4.0):
- before: 6 failed, 6 passed in tests/test_gateddirective.py
- after: 12 passed
- full suite: 116 passed on that combination, and 116 passed on Sphinx 8.2.3
No regression fixtures needed regenerating, which confirms they are
theme-independent.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
mmcky
added a commit
that referenced
this pull request
Aug 24, 2026
The gated collapsed tests use the RST `.. solution-start::` form in the
`mybook` test root. This adds the MyST ```{solution-start}``` counterpart in
the `gateddirective` root, so the directive-option parsing both parsers feed
into is exercised from each side.
That root was unusable while its `sphinx_book_theme` setting was breaking CI on
Sphinx 6 and 7, which is why the earlier gated test was written against
`mybook` instead. #88 has since switched it to alabaster, so it is available
again.
The `mybook` fixture stays as the primary gated test: it is self-contained, it
sits alongside the rest of the collapsed suite so confoverrides stay
consistent, and it avoids executing the matplotlib code cells the
`gateddirective` root builds.
Verified: 134 tests pass.
Refs #85
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Unbreaks CI, which is currently red on
mainfor a dependency-drift reason unrelated to any code change.The failure
Six tests in
tests/test_gateddirective.pyfail on the Sphinx 6 and 7 jobs with:sphinx.errors.ThemeError: An error happened in rendering the page exercise./ImportError: cannot import name '_get_toctree_ancestors' from 'sphinx.environment.adapters.toctree'raised from
pydata_sphinx_theme/toctree.py. Current pydata-sphinx-theme calls a Sphinx API that does not exist in Sphinx 6 or 7.Nothing in this repo changed. Main's last CI run was 2025-11-17, before the theme released the change, so the breakage has been latent since then and shows up on any PR opened today.
The fix
tests/books/test-gateddirective/conf.pywas the only HTML test root using a third-party theme. The other three already usealabaster; this brings the fourth into line.The theme is incidental to what these tests check — the regression fixtures capture only the
div.exercise/div.solutionmarkup this extension generates, so no third-party theme is needed to exercise them. Depending on one couples the whole suite to that theme's Sphinx support matrix.test-simplebookstill namessphinx_book_theme, but it is only ever built with thelatexbuilder, which never loads an HTML theme, so it is unaffected and left alone.Pinning the theme was considered and rejected. It would need a per-Sphinx-version pin, and it would rot again on the theme's next release. Removing the dependency from the HTML test path ends the whole class of failure instead.
Verification
Reproduced the exact failing CI combination locally — Python 3.13, Sphinx 6.2.1, pydata-sphinx-theme 0.20.0, sphinx-book-theme 1.4.0:
tests/test_gateddirective.pyAlso 116 passed on Sphinx 8.2.3.
No regression fixtures needed regenerating, which independently confirms they are theme-independent.
Note for follow-up (not changed here)
sphinx-book-themeis a hard runtime dependency of the package itself (dependenciesinpyproject.toml), which is unusual for a Sphinx extension — it means installing sphinx-exercise pulls in a theme and, transitively, pydata-sphinx-theme. Worth a separate look, but out of scope for a CI fix.🤖 Generated with Claude Code