New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
python 3.7.2 rc1 bumped sphinx requirements a bit too much #79653
Comments
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 c03bf0a
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 |
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:
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 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. |
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. |
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:
bugs.python.org fields:
The text was updated successfully, but these errors were encountered: