[ANNOUNCEMENT] Potential Breaking Changes in Sphinx 7.2.x

[picnixz]

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:

• Sphinx 7.2.0 problems with pathlib.Path instead of string paths #11605

cc @AA-Turner @humitos

[AA-Turner]

Sphinx 7.2.2 has been released, which contains fixes for Furo, and three other bugs.

A

[picnixz]

@AA-Turner thank you very much ! (maybe you could edit the announcement, since it appears I cannot re-edit it?)

[pradyunsg]

Adding 8e730ae to the list here -- it changed the behavior such that data-content_root needs to be set (it moved from a script without "use strict"; to a script that contains it).

Before:

document.getElementById("documentation_options").getAttribute('data-url_root')

After:

document.documentElement.dataset.content_root

It shouldn't affect themes that use base.html as-is from Sphinx; which... well, that's most theme. Furo doesn't and I'll be fixing that in a few minutes.

PS: Even though this release has been slightly disruptive, I do want to note that I appreciate the work that Sphinx's maintainers (notably @AA-Turner lately) have been doing! ^.^

[AA-Turner]

Sphinx 7.2.3 has been released.

A

[AA-Turner]

Sphinx 7.2.4 has been released.

A

[AA-Turner]

Sphinx 7.2.5 has been released.

A

[picnixz]

With Sphinx 7.2.6 being released, I think this issue can be closed. Anyone is free to reopen if they think that a change introduced between 7.2.0 and 7.2.5 is breaking.