gh-99380: Update to Sphinx 5.3.0

[AA-Turner]

• Issue: gh-99380

[AA-Turner]

Rendered: https://github.com/python/cpython/suites/9258549124/artifacts/433345867

[hugovk]

With the PR, there some extra lines in the footer, extending from the sidebar collapser thing (Chrome 106, macOS).

PR on left, main on right:

[AA-Turner]

Oh, it looks like two sidebar buttons are being added. In which case we revert to python-docs-theme for the JS/CSS changes to be merged...

A

[AA-Turner]

I've temporarily updated the python-docs-theme version to point at https://github.com/python/python-docs-theme/pull/127, to demonstrate the fix in that PR.

A

[CAM-Gerlach]

Especially if we're going to backport this change to 3.11 (which might also enable the dark theme there), we should add a job to build the docs on the minimum Sphinx version specified in the conf.py, so we can continue to verify everything will build (without warnings) on the minimum version we support redistributors using, as we have for the past. This will allow us to be more flexible with keeping all supported docs versions in sync and up to date with the latest Sphinx changes and improvements.

We also have to consider if we want to retain the now opt-out option for listing functions, classes, etc. in the toctree enabled, since this PR effectively flips that switch. Maybe it should be disabled for now and enabled in a separate PR after appropriate discussion (on Discourse, etc)?

[AA-Turner]

We've spoken about a minimum build for a while -- whilst I don't think it should block this work, I'll open a new PR to that effect (do you think we need a new issue to discuss that?).

I'm biased, as I added the feature, but I think it is a real usability win to have the direct links, and so long as the theme responds reasonably (eg on long names), which I'll test, I think we should keep the defaults as a net benefit (especially in reference-type documentation).

A

[AA-Turner]

Cross-linking #103904 for the oldest-supported testing.

A

[AA-Turner]

To resolve: ToC directives, e.g. https://deploy-preview-99381--python-cpython-preview.netlify.app/library/index.html

[miss-islington-app[bot]]

Thanks @AA-Turner for the PR 🌮🎉.. I'm working now to backport this PR to: 3.11, 3.12. 🐍🍒⛏🤖 I'm not a witch! I'm not a witch!

[miss-islington-app[bot]]

Sorry, @AA-Turner, I could not cleanly backport this to 3.12 due to a conflict. Please backport using cherry_picker on command line.

cherry_picker e6495159f6f2ca4fe3b5143c62fc2ad5873ef54f 3.12

[miss-islington-app[bot]]

Sorry, @AA-Turner, I could not cleanly backport this to 3.11 due to a conflict. Please backport using cherry_picker on command line.

cherry_picker e6495159f6f2ca4fe3b5143c62fc2ad5873ef54f 3.11

[bedevere-app[bot]]

GH-114341 is a backport of this pull request to the 3.12 branch.

[bedevere-app[bot]]

GH-114342 is a backport of this pull request to the 3.11 branch.