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/31bf9b7e71c3fee3b7866ffdc0f70f4525a490d9
(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/MY5EDNHE7FSOULBRIUATB2V4FRKFQDNE/
Code of Conduct: http://python.org/psf/codeofconduct/


--
--Guido van Rossum (python.org/~guido)
Pronouns: he/him (why is my pronoun here?)