The Python documentation is now compatible with Sphinx 3.2 and newer
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.
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/
-- --Guido van Rossum (python.org/~guido) *Pronouns: he/him **(why is my pronoun here?)* <http://feministing.com/2015/02/03/how-using-they-as-a-singular-pronoun-can-c...>
participants (3)
-
Guido van Rossum -
Stephen J. Turnbull -
Victor Stinner