Sphinx 5 compatibility

[pradyunsg]

Sphinx 5 was recently released, and a lot of our repositories have an upper-bound dependency pin that prevents users from installing it. This is an issue for tracking the removal of this upper bound across our repositories.

Repositories that need to be made Sphinx-5 compatible

We have a bunch of repositories, that contain a pin preventing users from using Sphinx 5. This is a checklist to track upgrading/updating them for Sphinx 5 support:

• https://github.com/executablebooks/jupyter-book: UPGRADE: myst-nb and many other dependencies jupyter-book/jupyter-book#1842
• https://github.com/executablebooks/sphinx-book-theme: Support Sphinx 5 / docutils >= .18 sphinx-book-theme#592
• https://github.com/executablebooks/sphinx-tabs
• https://github.com/executablebooks/MyST-NB
• https://github.com/executablebooks/sphinx-thebe
• https://github.com/executablebooks/sphinx-jupyterbook-latex: Support the latest version of Sphinx and make a release sphinx-jupyterbook-latex#120
• https://github.com/executablebooks/sphinx-panels (deprecated)
• https://github.com/executablebooks/sphinx-multitoc-numbering
• https://github.com/executablebooks/MyST-Parser
• https://github.com/executablebooks/sphinx-design
• https://github.com/executablebooks/sphinx-external-toc
• https://github.com/executablebooks/rst-to-myst

Useful links

• A GitHub Code Search that searches for Sphinx < 5 in config files
• Docutils changelog
• Sphinx changelog
• Sphinx deprecated APIs

Rough checklist for each repo

• Check changelog links above for any relevant changes
• Uncap the version in setup.py or pyproject.toml in a PR, and re-confirm that the tests pass.
• Double check the docs to make sure that no obvious problems have been introduced in the end-result.
• Merge the PR
• Then make a new release of the repository.
• Then check that box in the meta-issue
• And close the meta-issue when all is finished.

[choldgraf]

Thanks for opening this one @pradyunsg - I added a few extra contextual information in case it helps others!

[pradyunsg]

We should also check the docutils changelog!

[choldgraf]

Good point, have updated the top comment further!

[psychemedia]

I note that this is still an open issue, and that Sphinx is now at v7.1.2. Are there any upgrade plans, or blockers that require the legacy version of sphinx?

A saving grace is perhaps that for folk who use chatgpt to "search" documentation, the chatGPT 2021 cut-off was around about v4...