Sphinx conf.py needs_version entry is outdated

[timhoffm]

BPO	42820
Nosy	@terryjreedy, @JulienPalard, @timhoffm

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = None
created_at = <Date 2021-01-04.01:28:14.798>
labels = ['docs']
title = 'Sphinx conf.py needs_version entry is outdated'
updated_at = <Date 2021-01-08.23:35:42.562>
user = 'https://github.com/timhoffm'

bugs.python.org fields:

activity = <Date 2021-01-08.23:35:42.562>
actor = 'terry.reedy'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2021-01-04.01:28:14.798>
creator = 'timhoffm'
dependencies = []
files = []
hgrepos = []
issue_num = 42820
keywords = []
message_count = 2.0
messages = ['384305', '384697']
nosy_count = 4.0
nosy_names = ['terry.reedy', 'docs@python', 'mdk', 'timhoffm']
pr_nums = []
priority = 'normal'
resolution = None
stage = None
status = 'open'
superseder = None
type = None
url = 'https://bugs.python.org/issue42820'
versions = []

[timhoffm]

The sphinx conf.py entry needs_version=1.8 (

cpython/Doc/conf.py

Line 48 in 1470edd

needs_sphinx = '1.8'

)

is not in sync with the doc build requirements (

cpython/Doc/requirements.txt

Line 6 in 1470edd

sphinx==3.2.1

)

Possible solutions:
a) Drop the needs_version config value. It's optional.
b) Make sure to update both places.
c) Or at minimum add a comment that needs_version is only a safeguard against very old sphinx versions but is not necessarily sufficient to build.

[terryjreedy]

This is related to bpo-42843, which is about deciding what the min sphinx should be. Since the alternative to 3.2 is some 2.x, 1,8 is certainly wrong.

[JulienPalard]

This is now related to #92318, the new needs_sphinx is 3.2, cc @sorcio.

[sorcio]

Since the time of the discussion in #87009, it looks like the mentioned restrictions are now mostly gone:

• Debian stable now only has Sphinx 3.4.
• For deadsnakes, the maintainer confirmed that bumping Sphinx version is not an issue anymore.
• Ubuntu LTS has Sphinx 3.5.
• RHEL9 has Sphinx 3.4
• Fedora and Ubuntu were already ok last year
• SUSE is less clear to me. I think the rolling openSUSE is already using Sphinx 4.5.0 for Python 3.10. But Leap also has a Python 3.10 package which I think still builds doc with Sphinx 2.3.

Apparently for 3.11 we are clear. Since #92318 was also backported to 3.10, the SUSE package maintainers might appreciate a heads up.

[ambv]

Fixed on 3.10, 3.11, and 3.12.