This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

Title: What min_sphinx for Python 3.10
Type: Stage: resolved
Components: Documentation Versions: Python 3.10
Status: closed Resolution: not a bug
Dependencies: Superseder:
Assigned To: mdk Nosy List: corona10, doko, mdk, vstinner
Priority: normal Keywords: patch

Created on 2021-01-06 16:52 by mdk, last changed 2022-04-11 14:59 by admin. This issue is now closed.

Pull Requests
URL Status Linked Edit
PR 24142 closed mdk, 2021-01-06 16:54
PR 24282 merged mdk, 2021-01-21 02:08
Messages (8)
msg384512 - (view) Author: Julien Palard (mdk) * (Python committer) Date: 2021-01-06 16:52
According to [1] there's no concensus on which minimum Sphinx version we should use for Python 3.10.

"sadly" since which make use of a Sphinx 3.2.0 only feature, we should bump it to 3.2, but it may not work for everybody.

msg384514 - (view) Author: Julien Palard (mdk) * (Python committer) Date: 2021-01-06 17:04
In favor of Sphinx 3 only :

- We have :no-trim-doctest-flags: which fixes
- backslash handing is different in Sphinx 2 and Sphinx 3:

In favor of keeping compatibility with Sphinx 2 :

- Some distribs may want/need to ship Python 3.10 along with Sphinx 2?

So I'm personally in favor of a full witch to Sphinx 3 with Python 3.10, but I'm open to hear everybody.
msg384950 - (view) Author: STINNER Victor (vstinner) * (Python committer) Date: 2021-01-12 14:57
> Some distribs may want/need to ship Python 3.10 along with Sphinx 2?

In my experience, Linux distributions prefer to only ship a single Sphinx version. The question is more which Linux distributions are stuck at Sphinx 2 only?

If there is a short list of Linux distributions which cannot use Sphinx 3, even just to build the Python documentation, would it be acceptable for them to stop shipping the Python documentation?

In Fedora, the Python documentation is a separated package. For example, it allows us to upgrade Python while Fedora Rawhide was upgrade to Sphinx 3 but the Python documentation was not compatible with Sphinx 3 (fixed in bpo-40204).

If you ask *me*: I mostly care about Fedora which already uses Sphinx 3.2, so I'm fine with requiring Sphinx 3.2 (the Python documentation is *not* compatible with Sphinx 3.0 and 3.1: see bpo-40204).

If the minimum required Sphinx version changes, please document it properly at:
msg384959 - (view) Author: STINNER Victor (vstinner) * (Python committer) Date: 2021-01-12 16:23
Ah, the issue is also being discussed in PR 24142 comments.
msg384963 - (view) Author: STINNER Victor (vstinner) * (Python committer) Date: 2021-01-12 16:38
* Fedora 33 (stable) ships python3-sphinx 3.2.1-1 and python3.10 version 3.10.0~a3-1 (the alpha4 is under tests).
* Debian Buster (stable) ships python3-sphinx 1.8.4-1 and python3 version 3.7.3-1
* Debian Sid (unstable) ships python3-sphinx 3.4.3-1 and python3 version 3.9.1-1.
* Ubuntu Groovy (stable) ships python3-sphinx 3.2.1-1 and python3 version 3.8.6-0ubuntu1
* Ubuntu Hirsute (dev) ships python3-sphinx 3.3.1-1 and python3 version 3.9.0-3ubuntu1

In this list, requiring Sphinx 3.2+ to build Python 3.10 documentation would only be an issue on Debian Buster.

I didn't check Red Hat RHEL or SUSE SLE. If they want to ship Python 3.10 but only have an old Sphinx, they can either use a newer Sphinx to build the doc, or ship Python 3.10 with no doc (since it would not be the "system Python", it may be an acceptable tradeoff).
msg384965 - (view) Author: STINNER Victor (vstinner) * (Python committer) Date: 2021-01-12 16:46
There is a PPA on Ubuntu for Python 3.10. The PPA maintainer considers the drop the documentation, see discussion at:
msg385021 - (view) Author: Matthias Klose (doko) * (Python committer) Date: 2021-01-13 11:30
Ubuntu 20.04 LTS still sees subminor Python 3.8 version updates, and needs to use sphinx 1.8.5.
msg385631 - (view) Author: Julien Palard (mdk) * (Python committer) Date: 2021-01-25 14:46
New changeset 5c1f15b4b1024cbf0acc85832f0c623d1a4605fd by Julien Palard in branch 'master':
bpo-42843: Keep Sphinx 1.8 and Sphinx 2 compatibility (GH-24282)
Date User Action Args
2022-04-11 14:59:39adminsetgithub: 87009
2021-01-25 14:47:16mdksetstatus: open -> closed
resolution: not a bug
stage: patch review -> resolved
2021-01-25 14:46:17mdksetmessages: + msg385631
2021-01-21 02:08:31mdksetpull_requests: + pull_request23103
2021-01-13 11:30:12dokosetnosy: + doko
messages: + msg385021
2021-01-12 16:46:43vstinnersetversions: + Python 3.10
2021-01-12 16:46:39vstinnersetmessages: + msg384965
2021-01-12 16:38:07vstinnersetmessages: + msg384963
2021-01-12 16:23:59vstinnersetmessages: + msg384959
2021-01-12 14:57:01vstinnersetmessages: + msg384950
2021-01-12 14:02:14corona10setnosy: + vstinner, corona10
2021-01-06 17:04:03mdksetmessages: + msg384514
2021-01-06 16:54:47mdksetkeywords: + patch
stage: patch review
pull_requests: + pull_request22971
2021-01-06 16:52:46mdkcreate