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.

"for no reason"

I guess that it's related to this change:

commit c03bf0ae794c3bec9b56f38164535fd1f5bfc04a
Author: Adrian Liaw <adrianliaw2000@gmail.com>
Date:   Mon Nov 5 05:04:51 2018 +0800

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

Extract:

diff --git a/Doc/conf.py b/Doc/conf.py
index 6060ac176c..eb57ee0c93 100644
--- a/Doc/conf.py
+++ b/Doc/conf.py
@@ -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:

https://www.sphinx-doc.org/en/master/changes.html#release-1-6-6-released-jan-08-2018

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

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:

- https://github.com/sphinx-doc/sphinx/issues/5561 (release in 1.8.2)
- https://github.com/sphinx-doc/sphinx/pull/5559 (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.

"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.

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 conf.py 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.

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 docs.python.org 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.

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)
https://github.com/python/cpython/commit/a9ed8fcdbaeccdb82593525b170fb0544202eeda

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.

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)
https://github.com/python/cpython/commit/371ca0bb8f5eaa0dcbd3fa2f878398285488d47f