[ANNOUNCEMENT] Potential Breaking Changes in Sphinx 7.2.x #11608
Description
Sphinx 7.2.5
Sphinx 7.2.5 has been released with fixes for all known outstanding issues
Please upgrade to Sphinx 7.2.5, and report any new failures
A
Original issue
I am opening this issue in order to track the issues related to the API changes that Sphinx 7.2 implemented. Since most of the issues are hard to hotfix, I would just recommend using an older version of Sphinx until this is fixed (probably in 7.2.1).
TocTree related API
In #11565, we decided to refactor the toctree adapter. This caused issues with pydata theme and other themes as well. Most of the issues are caused by the fact that the TocTree adapter exposed as a class contained public methods that extensions used. However, TocTree was never considered as a public API (it is not documented at all, see pydata/pydata-sphinx-theme#1404 (comment)), so we did not expect that this would lead to breaking changes (see pydata/pydata-sphinx-theme#1404 (comment)).
We are planning to something about this (maybe we could expose part of the private API).
Issues:
- Attribute Error when running the docs #11604
toctree(...)API changed in Sphinx 7.2 #11607- Incompatibility with Sphinx dev pydata/pydata-sphinx-theme#1404
Javascript and CSS issues
Before, Javascript and CSS files were represented internally using classes that may also behave as strings. Many extensions relied on that and are broken (or may be broken). The string representation was originally intended for backward compatibility but way before these objects were introduced and should not have been used as such. It was now deprecated in #11582 (but we should have kept the str behaviour until removing completely the old objects).
Another breaking change is app.add_js_file (everything I say about JS files is essentially valid for CSS files). Before app.add_js_file also injected the JS file into the builder's JS files, which was a reference to ctx['script_files'] in the HTML context that extensions could play with. However, if extensions call app.add_js_file in their own html-page-context handler, the JS files will NOT be added to the builder's files, and not to ctx['script_files'] neither. So no JS file will be injected (see #11586 (comment)).
We are planning to something about this (either we revert to the old behaviour or fix the current one).
Issues:
- readthedocs flyout not visible on https://www.sphinx-doc.org/ #11586 (comment)
- search does not work on the documentation website #11606
- Incompatibility with Sphinx 7.2 readthedocs/sphinx_rtd_theme#1502
- Theme breaks with Sphinx 7.2.0 kai687/sphinxawesome-theme#1464
- Furo is broken on Sphinx 7.2.0 and 7.2.1 pradyunsg/furo#693
pathlib.Path objects vs plain strings
In #11526, we changed most of the str objects that behaved like a path to pathlib.Path objects. This breaks extensions or themes relying on the fact that the object was a string.
Issues: