Skip to content

Drop the archived readthedocs-sphinx-ext, which breaks the docs build on Sphinx 8.2+ - #1327

Open
dylanpulver wants to merge 1 commit into
CLIMADA-project:mainfrom
dylanpulver:docs/drop-archived-readthedocs-sphinx-ext
Open

dylanpulver wants to merge 1 commit into
CLIMADA-project:mainfrom
dylanpulver:docs/drop-archived-readthedocs-sphinx-ext

Conversation

@dylanpulver

Copy link
Copy Markdown

The Read the Docs build is failing on current PRs, and it will fail on every new one. readthedocs-sphinx-ext runs this on each page:

if inject_css and theme_css not in app.builder.css_files:

css_files was removed from Sphinx's HTML builders, so the attribute access raises before the sphinx.version_info < (1, 8) guard below it can help. Since doc pins readthedocs-sphinx-ext>=2.2 but leaves sphinx unpinned, each build resolves a newer Sphinx and dies:

Extension error (readthedocs_ext.readthedocs)!
  if inject_css and theme_css not in app.builder.css_files:
AttributeError: 'StandaloneHTMLBuilder' object has no attribute 'css_files'

That is build 34785300 verbatim, and it reproduces locally with .[doc] and doc/conf.py unchanged.

Bisected against the extension at 2.2.5: Sphinx 8.1.3 builds, 8.2.3 and everything after fails.

Why remove it rather than pin Sphinx. The extension is archived upstream, so it will not be fixed and a pin would hold CLIMADA on Sphinx 8.1 indefinitely. Its job is injecting sphinx_rtd_theme or badge_only CSS plus the old doc-embed JS; CLIMADA uses sphinx-book-theme, so that CSS was never wanted here, and Read the Docs Addons injects the flyout and search itself now. Nothing under doc/ references readthedocs_build, readthedocs_ext or those assets, and conf.py's own readthedocs config value is declared in its setup() and is unaffected.

With the extension dropped, the same command Read the Docs runs succeeds:

build succeeded, 52 warnings.

No warning mentions Read the Docs or CSS, and the warning count is what the build already carried.

🤖 Generated with Claude Code

https://claude.ai/code/session_011M5uTyCU4WcNTsPvGrErDo

Its update_body reads app.builder.css_files, removed from Sphinx builders
in 8.2, so every docs build fails once pip resolves a current Sphinx. The
package is archived upstream, so it will not be fixed, and CLIMADA uses
sphinx-book-theme rather than sphinx_rtd_theme, so the CSS the extension
exists to inject was never wanted here. Read the Docs Addons injects the
flyout and search itself.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011M5uTyCU4WcNTsPvGrErDo
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant