Thanks Victor! This is a great improvement.
On Fri, Sep 18, 2020 at 8:50 AM Victor Stinner vstinner@python.org wrote:
Hi,
The Python 3.8, 3.9 and 3.10 documentation can now be built with Sphinx 3.2+, and Sphinx 2 is still supported. Sphinx 3.0 and 3.1 are not supported.
On our continuous integration (CI), the Python 3.10 documentation is now built with Sphinx 3 (version 3.2.1), whereas the Python 3.8 and Python 3.9 documentation is still built with Sphinx 2 (just updated to version 2.4.4). Also, the Sphinx version is now only pinned in a single file (Doc/requirements.txt), rather than 3 files (Doc/requirements.txt, .travis.yml and Doc/Makefile).
Thanks to everyone who helped to fix all these documentation build issues!
--
Sphinx 3.0 released in April 2020 is backward incompatible with Sphinx 2: the C domain is stricter, and it is no longer possible to build the Python documentation with Sphinx 3.0.
I discussed with the Sphinx maintainers. They accepted to add two new options to Sphinx 3.2 to add an opt-in Sphinx 2 compatibility mode:
# bpo-40204: Allow Sphinx 2 syntax in the C domain c_allow_pre_v3 = True
# bpo-40204: Disable warnings on Sphinx 2 syntax of the C domain since the # Python documentation is built with -W (warnings treated as errors). c_warn_on_allowed_pre_v3 = False
I modified Doc/conf.py to use these options.
I also fixed other real documentation issues, discovered by stricter Sphinx 3: https://bugs.python.org/issue40204
--
By the way, all warnings produced during the documentation build have been fixed as well: https://bugs.python.org/issue35293
It took two years (I created the issue in November 2018) to fix all these warnings! Multiple projects got fixes:
- Update our Doc/tools/extensions/pyspecific.py extension to fix
Sphinx RemovedInSphinx40Warning, by Dong-hee Na
- jinja2:
https://github.com/pallets/jinja/commit/31bf9b7e71c3fee3b7866ffdc0f70f4525a4... (import collections ABC)
- python-babel: https://github.com/python-babel/babel/pull/609 (import
collections ABC)
- docutils: https://sourceforge.net/p/docutils/bugs/373/ (version 0.16
fixed SyntaxWarning on invalid escape sequence)
- etc.
--
The last remaining minor issue is my proposition to also update Sphinx in docsbuild-scripts (docs.python.org): https://github.com/python/docsbuild-scripts/issues/95
Victor
Night gathers, and now my watch begins. It shall not end until my death. _______________________________________________ Python-Dev mailing list -- python-dev@python.org To unsubscribe send an email to python-dev-leave@python.org https://mail.python.org/mailman3/lists/python-dev.python.org/ Message archived at https://mail.python.org/archives/list/python-dev@python.org/message/MY5EDNHE... Code of Conduct: http://python.org/psf/codeofconduct/