pradyunsg
furo: support sphinx 9
Rather than incrementing the upper bound on the version of Sphinx, could we instead remove the upper bound entirely? I personally think that approach has ample evidence to support it:
- Should You Use Upper Bound Version Constraints?
- Black project drops upper bounds
- Requires-Python upper limits (slightly different context, but still relevant)
👋🏽
It's been less than 2 weeks since the release, and I'm getting links to d.p.o. threads where I participated / blog posts that I reviewed early drafts of... I guess this is a properly popular project now! 😅
I do have this PR (and a few more things around this project) on deck for the volunteer-responsibility things I wanna get to. All of that is definitely gonna stay lower priority than "figure out marriage details & logistics" for me in the near future tho.
For this PR -- I'd wanna make sure that nothing actually breaks for users with this Sphinx upgrade, which usually comes with a docutils upgrade that changes the HTML output. If a couple of folks could do that and let me know that nothing is broken/changed in the "kitchen sink" with this upgrade, that'd be helpful -- this would be a quick merge + release if I can get those confirmations!
Hello @pradyunsg ,
thanks for taking care even if there are obviously more important things in life happening 😄 .
I update sphinx in an inner source project (uv pip install -U sphinx) and then run it (sphinx-build -d docs/_build/doctrees -b html -a -W -j 4 docs docs/_build/html) without any issues. The output looks clean, no navigation issues or so. I also checked the browser developer console and there were no warnings or errors at all
For https://spack.readthedocs.io/en/latest, I did a diff of the generated HTML after "prettifying" them with tidy -i -wrap 0 -m *.html **/*.html and the diff is mostly:
- <link rel="shortcut icon" href="../_static/favicon.ico" /><!-- Generated with Sphinx 8.2.3 and Furo 2025.07.19.dev1 -->
+ <link rel="shortcut icon" href="../_static/favicon.ico" /><!-- Generated with Sphinx 9.0.4 and Furo 2025.09.25.dev1 -->
...
- <script src="../_static/doctools.js?v=9bcbadda"></script>
- <script src="../_static/sphinx_highlight.js?v=35101b8e"></script>
+ <script src="../_static/doctools.js?v=fd6eb6e6"></script>
+ <script src="../_static/sphinx_highlight.js?v=6ffebe34"></script>
and a couple changes like
+height="203"
src="_images/original_package_architecture.png"
-style="width: 531.0px; height: 203.4px;"
+width="531"
due to the upgrade of docutils, which is intentional and desirable to fix text reflow issues during page load. Otherwise it's mostly changes to internal javascript files.
I do see a regression in Sphinx 9 related to :no-value: in autodoc, which I'll report upstream.
Thanks @haampie and @kasium for that! ^.^
Looks like I can't build Furo's own docs with Sphinx 9+ due to https://github.com/executablebooks/MyST-Parser/issues/1042. Ended up figuring out relevant shenanigans and confirmed that there's one small markup change: https://gist.github.com/pradyunsg/1053aa35d8944c22e61ebffca093dd3d
main now has d27cab5e448c44e366577a80bf99beee6fa941a5 which is a functional superset of this (with the bump to the minimum range as well as max range + the stylesheet change as well). Onward to figuring out sphinx-theme-builder failing on Python 3.14 now, then I'll cut a release tomorrow.
(@haampie I hope you don't mind that I ended up including the version bump in that commit directly, instead of merging this PR -- realised after that doing a merge + my changes after would've probably been a nicer way of doing this. 🙈)
