backported patch requires new sphinx, minimum sphinx version was not bumped

[asottile]

BPO	35605
Nosy	@ned-deily, @zooba, @asottile, @JulienPalard
PRs	[3.6] bpo-35605: Fix documentation build for sphinx<1.6 #11368 [3.6] bpo-35605: Fix documentation build for sphinx<1.6 #11368 [3.6] bpo-35605: Fix documentation build for sphinx<1.6 #11368 [2.7] bpo-35605: Fix documentation build for sphinx<1.6 #12413 [3.6] bpo-35605: Fix documentation build for sphinx<1.6 #14576

^{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 = 'https://github.com/JulienPalard'
closed_at = <Date 2019-07-03.22:40:37.797>
created_at = <Date 2018-12-28.17:00:36.305>
labels = ['easy', 'build', 'docs']
title = 'backported patch requires new sphinx, minimum sphinx version was not bumped'
updated_at = <Date 2019-07-03.22:43:34.648>
user = 'https://github.com/asottile'

bugs.python.org fields:

activity = <Date 2019-07-03.22:43:34.648>
actor = 'ned.deily'
assignee = 'mdk'
closed = True
closed_date = <Date 2019-07-03.22:40:37.797>
closer = 'ned.deily'
components = ['Build', 'Documentation']
creation = <Date 2018-12-28.17:00:36.305>
creator = 'Anthony Sottile'
dependencies = []
files = []
hgrepos = []
issue_num = 35605
keywords = ['patch', 'patch', 'patch', 'easy']
message_count = 17.0
messages = ['332665', '332666', '332675', '332677', '332680', '332681', '332682', '332685', '332736', '332944', '334802', '334803', '338275', '347242', '347244', '347245', '347246']
nosy_count = 5.0
nosy_names = ['ned.deily', 'docs@python', 'steve.dower', 'Anthony Sottile', 'mdk']
pr_nums = ['11368', '11368', '11368', '12413', '14576']
priority = 'low'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = None
url = 'https://bugs.python.org/issue35605'
versions = ['Python 3.6']

[asottile]

Noticed this while packaging 3.6.8 for deadsnakes (ubuntu ppa)

This patch: #11251

Requires a version of sphinx where sphinx.util.logging.getLogger is available. It appears that the first version which that was available was 1.6: sphinx-doc/sphinx@6d4e645#diff-db360b033c6011189d978db1a4b7dcb7

For example, on ubuntu xenial (16.04) the newest packaged version of python3-sphinx available is 1.3.6 (released 2016-02) which satisfies the "minimum version":

cpython/Doc/conf.py

Lines 36 to 37 in 3c6b436

	# Require Sphinx 1.2 for build.
	needs_sphinx = '1.2'

I hacked around it in this case by just using logging.getLogger: deadsnakes/python3.6@9ba2234

I'm not sure what the right answer is here, bumping the minimum version will make it _harder_ for packagers -- though I understand continuing to support old (2 years ago) things can be cumbersome.

[asottile]

oops, pressed the button too quickly, meant to mention that sphinx 1.6 was released 2017-05

[zooba]

We need Ned's approval to fix anything in 3.6 now. Typically we do consider build issues, and this one is fairly innocent (the affected code should only be used on Windows, but the import may trigger elsewhere).

I'd be happy to take a patch to use logging when the sphinx one is not found. We more or less enforce a newer version of Sphinx on the platforms where it matters, but for those restricted by their distros we can pretty easily help out.

[ned-deily]

I would view this as a build regression in 3.6.8 so I would accept a fix for the 3.6 branch.

[asottile]

If I add a patch which is essentially:

try: # sphinx>=1.6
from sphinx.util.logging import getLogger
except ImportError: # sphinx<1.6
from logging import getLogger

will that be fine?

and should I open that against 3.7 to be backported or just against 3.6 (I also ran into the same issue when backporting 3.7.2 for xenial -- but there I adjusted the minimum sphinx version: deadsnakes/python3.7@c27b89b )

[zooba]

I think we're okay to increase the minimum version on the active branches.

[asottile]

I assume that means I should only target 3.6 -- does the patch look like the right approach? I can make a PR

[ned-deily]

Julien (@mdk) is the doc builds expert.

[JulienPalard]

The patch (try/except) to make https://github.com/python/cpython/pull/11251/files work with what Doc/conf.py says about minimum sphinx version (1.2) is OK for me.

No need to apply it on 3.7 which needs_sphinx 1.6.6 according to its Doc/conf.py.