Increase minimum supported Sphinx to 4.2

[AA-Turner]

Documentation

#108184 introduces a nice improvement to https://docs.python.org/dev/library/string.html by linking the tokens. However linking to other groups was only introduced in Sphinx 3.5 (sphinx-doc/sphinx#8247).

Using the same survey as #86986 (comment):

• Ubuntu 23.04: Python 3.11, Sphinx 5.3.0
• Debian stable: Python 3.11, Sphinx 5.3.0
• RHEL doesn't seem to list versions
• Fedora 38: Python 3.11, Sphinx 5.3.0
• OpenSUSE rolling: Sphinx 7.2.4

Updated survey: #109209 (comment)

A

Linked PRs

• GH-109209: Bump the minimum Sphinx version to 4.2 #109210
• [3.12] GH-109209: Bump the minimum Sphinx version to 4.2 (GH-109210) #109636
• [3.11] GH-109209: Bump the minimum Sphinx version to 4.2 (GH-109210) #109637

[AA-Turner]

Ahh. Sphinx 3.5.4 doesn't work on Python 3.10.1 and newer, as it tries to import types.Union: https://github.com/sphinx-doc/sphinx/pull/8803/files#diff-f41e19a9b77f4670d4dd1ea61f80d518c93a4403112fd7e91253dac47cf55fe5

The venv I was using locally had Python 3.9, so I was blissfully unaware.

From the survey in the issue, 4.2 (where this was fixed: https://github.com/sphinx-doc/sphinx/pull/9513/files#diff-f41e19a9b77f4670d4dd1ea61f80d518c93a4403112fd7e91253dac47cf55fe5) is also fine, so I'll update this PR.

The alternative would be to run the workflow on Python 3.9, if keeping Sphinx 3.5 would be preferred.

A

[serhiy-storchaka]

I'm waiting for 7.2 for the :no-typesetting: option. But it won't be soon.

[AA-Turner]

@doko42 @stefanor @mitya57 -- we're considering raising the minimum required Sphinx to a newer version. It seems that Debian stable has Python 3.11 and Sphinx 5.3 -- it would be useful to understand what would be useful/inconvenient to you as redistributors.

For example if we went all the way to Sphinx 7.2 (for the feature Serhiy mentioned), and backported that to Python 3.11 and 3.12, how painful would that be?

A

[AA-Turner]

@vstinner @hroncok @hrnciar @torsava -- as above, it would be useful to understand what would be useful/inconvenient to you from Fedora -- it seems that Fedora 38 has Python 3.11 and Sphinx 5.3.0.

From Fedora's perspective, if CPython went all the way to Sphinx 7.2 and backported that to Python 3.11 and 3.12, how painful would it be?

(Do you know if there are separate RHEL people to ask as well?)

A

[AA-Turner]

@marketayord @dirkmueller @danigm -- please may I ask the same questions as above for OpenSUSE?

A

[vstinner]

@vstinner @hroncok @hrnciar @torsava -- as above, it would be useful to understand what would be useful/inconvenient to you from Fedora -- it seems that Fedora 38 has Python 3.11 and Sphinx 5.3.0.

cc @befeleme

[hroncok]

@vstinner @hroncok @hrnciar @torsava -- as above, it would be useful to understand what would be useful/inconvenient to you from Fedora -- it seems that Fedora 38 has Python 3.11 and Sphinx 5.3.0.

• Fedora 40: 7.1.2 (we plan to update to 7.2 or newer eventually) @ Python 3.12
• Fedora 39: 6.2.1 @ Python 3.12
• Fedora 38: 5.3.0 @ Python 3.11
• Fedora 37: 5.0.2 @ Python 3.11 (end of life plan: 2023-11-14)

From Fedora's perspective, if CPython went all the way to Sphinx 7.2 and backported that to Python 3.11 and 3.12, how painful would it be?

Doing it in the main branch would be OK. Backporting that to 3.12 and 3.11 would mean we would no longer be able to build up-to-date documentation for Python in Fedora . We would need to come up with a solution. (One of the solutions is that we would keep the outdated documentation in Fedora, another is that we could build an alternate sphinx package in version 7.2 but that can still have an unforeseen impact on other packages...) It would not be the end of the world for us, but it would certainly not be convenient at all.

Do you know if there are separate RHEL people to ask as well?

The Python-Maint team at Red Hat (@encukou @vstinner @hrnciar @torsava @befeleme @stratakis @frenzymadness @hroncok) takes care of Python in Fedora Linux and RHEL both.

Nothing to worry about for RHEL, we don't build the documentation from the source there at all.

[mitya57]

Regarding Debian: we still have many packages which fail to build with Sphinx 7.x. See this list: https://bugs.debian.org/cgi-bin/pkgreport.cgi?tag=sphinx7.1;users=python-modules-team@lists.alioth.debian.org.

I want to give some more time for the maintainers to fix these bugs, but it's a few weeks, hopefully not months.