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