Title: python 3.7.2 rc1 bumped sphinx requirements a bit too much
Type: Stage: resolved
Components: Documentation Versions: Python 3.7
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: docs@python, doko, mdk, ned.deily, terry.reedy, vstinner
Priority: normal Keywords: 3.7regression, patch

Created on 2018-12-12 16:30 by doko, last changed 2018-12-24 16:31 by ned.deily. This issue is now closed.

Pull Requests
URL Status Linked Edit
PR 11192 merged mdk, 2018-12-17 11:22
Messages (10)
msg331705 - (view) Author: Matthias Klose (doko) * (Python committer) Date: 2018-12-12 16:30
python 3.7.2 rc1 bumped the build requirements apparently for no reason, now requiring sphinx 1.7 instead of 1.6.x before.  This is a major pain, if you want to provide the build including the documentation on a stable release.  Pretty please can we avoid such version bumps on the branches?

Plus the documentation seems to build fine with 1.6.7.
msg331707 - (view) Author: STINNER Victor (vstinner) * (Python committer) Date: 2018-12-12 16:35
"for no reason"

I guess that it's related to this change:

commit c03bf0ae794c3bec9b56f38164535fd1f5bfc04a
Author: Adrian Liaw <>
Date:   Mon Nov 5 05:04:51 2018 +0800

    Doc: Disable smartquotes for zh-tw, zh-cn, fr and ja translations (GH-9423)


diff --git a/Doc/ b/Doc/
index 6060ac176c..eb57ee0c93 100644
--- a/Doc/
+++ b/Doc/
@@ -41,13 +41,18 @@ today_fmt = '%B %d, %Y'
 # By default, highlight as Python 3.
 highlight_language = 'python3'
-# Require Sphinx 1.2 for build.
-needs_sphinx = '1.2'
+# Require Sphinx 1.7 for build.
+needs_sphinx = '1.7'
 # Ignore any .rst files in the venv/ directory.
 venvdir = os.getenv('VENVDIR', 'venv')
 exclude_patterns = [venvdir+'/*', 'README.rst']
+# Disable Docutils smartquotes for several translations
+smartquotes_excludes = {
+    'languages': ['ja', 'fr', 'zh_TW', 'zh_CN'], 'builders': ['man', 'text'],

According to Sphinx changelog, smartquotes_excludes is a new feature of Sphinx 1.6.6:
msg331711 - (view) Author: Ned Deily (ned.deily) * (Python committer) Date: 2018-12-12 17:17
Julien can give the definite answer.  But, sorry, I don't see this as a release blocker.  We've had to bump Sphinx versions for a number of reasons as the documentation has become more sophisticated between cycles and over a release cycle.  In fact, we're now using 1.8.2 for release builds.  And it shouldn't be an issue at all if one uses the doc Makefile venv target:

make venv
make html
msg331718 - (view) Author: Julien Palard (mdk) * (Python committer) Date: 2018-12-12 21:26
Hi Matthias,

Sorry to hear it's a pain for you. Can you explain in more details what hurt your workflow?

We bumped Sphinx, as Victor said, to fix rendering issues in those documentation translations: zh-tw, zh-cn, fr and ja, so it's not a feature or an ideology of "being up-to-date", we were fixing an issue in those 4 translations.

Please also note that in the near future we'll probably stick to a fresh version of Sphinx as we're expecting other fixes or features to land, I don't have all of them in mind but at least:

- (release in 1.8.2)
- (to be released in 2.0.0)

The colspan/rowspan thing is needed for the documentation of Python 3.8, so we'll have to bump to sphinx 2.0 for Python 3.8.
msg331755 - (view) Author: Matthias Klose (doko) * (Python committer) Date: 2018-12-13 11:11
"if one uses the doc Makefile venv target". which is not possible for distributions which are not allowed to use anything but the distro to build the distro.

so why bumping the version requirement to 1.7 instead of 1.6.6? Afaicu this is the required version.

I don't argue against introducing new build requirements in major versions, but having them introduced on the branches.
msg331873 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2018-12-14 21:44
Should we add '(subject to change in any release)' after
# Require Sphinx 1.7 for build.

Matthias, I presume you are on some Linux. Would a script to temporarily change to build the docs work for you?

To be reasonably sure that 1.6.6 is sufficient for all translations on all systems that care, I would think it should be part of a .rc release first.
msg331985 - (view) Author: Julien Palard (mdk) * (Python committer) Date: 2018-12-17 11:17
Hi Matthias,

I agree that for the smartquotes issue the 1.6.6 should be enough. But we had multiple small issues fixed in some versions of Sphinx. But mostly for translation and I don't think you're building the translations?

Also the needs_sphinx is only the minimum required version to build, it won't disallow me using sphinx 1.7 or 1.8 on to build the documentation.

The needs_sphinx flag only supports "micro" value since 1.4, but looks compatible with it before (04a8c26eabba3e728a5b74afd15f328f9235b2d0 in the sphinx repo).

So it looks OK to allow 1.6.6 as a minimum required version for 3.7, opening a PR on it.
msg332118 - (view) Author: Julien Palard (mdk) * (Python committer) Date: 2018-12-19 10:14
New changeset a9ed8fcdbaeccdb82593525b170fb0544202eeda by Julien Palard in branch '3.7':
bpo-35472: Doc: For Python 3.7 Sphinx 1.6.6 is enough. (GH-11192)
msg332119 - (view) Author: Julien Palard (mdk) * (Python committer) Date: 2018-12-19 10:18
Matthias, I downgraded the needs_sphinx to 1.6.6, as it does not disallow me to use an up-to-date sphinx in the doc server I'm ok with this.

Hope it helps.
msg332484 - (view) Author: Ned Deily (ned.deily) * (Python committer) Date: 2018-12-24 16:31
New changeset 371ca0bb8f5eaa0dcbd3fa2f878398285488d47f by Ned Deily (Julien Palard) in branch '3.7':
bpo-35472: Doc: For Python 3.7 Sphinx 1.6.6 is enough. (GH-11192)
Date User Action Args
2018-12-24 16:31:42ned.deilysetmessages: + msg332484
2018-12-19 10:18:01mdksetstatus: open -> closed
resolution: fixed
messages: + msg332119

stage: patch review -> resolved
2018-12-19 10:14:59mdksetmessages: + msg332118
2018-12-17 11:24:13mdksettitle: python 3.7.2 rc1 bumped the build requirements for no reason -> python 3.7.2 rc1 bumped sphinx requirements a bit too much
2018-12-17 11:22:16mdksetkeywords: + patch
stage: patch review
pull_requests: + pull_request10432
2018-12-17 11:17:32mdksetmessages: + msg331985
2018-12-14 21:44:43terry.reedysetnosy: + terry.reedy
messages: + msg331873
2018-12-13 11:11:33dokosetmessages: + msg331755
2018-12-12 21:26:57mdksetmessages: + msg331718
2018-12-12 17:17:07ned.deilysetpriority: release blocker -> normal

messages: + msg331711
2018-12-12 16:35:30vstinnersetnosy: + vstinner
messages: + msg331707
2018-12-12 16:32:18vstinnersetnosy: + mdk
2018-12-12 16:30:41dokocreate