The Python documentation can be found in the Doc/ directory of https://github.com/python/cpython/ It is quite big: 262k lines of .rst files (and 1300 of extensions written in Python: see Doc/tools/).

It is no longer possible to build the Python documentation with Sphinx 3, many syntax which were allowed previously ("tolerated"?) are now treated as errors: see https://bugs.python.org/issue40204 for details.

According to the Sphinx changelog, it is a deliberate that the C domain is more strict. Extract:

The C domain has been rewritten, with additional directives and roles. The existing ones are now more strict, resulting in new warnings.

The problem is that I fail to find a way to write a documentation which can be built and rendered properly with Sphinx 2 and Sphinx 3. Dropping Sphinx 2 support is not an option for the Python project. Too many Linux distributions currently build the Python documentation with Sphinx 2, and it seems like upgrading to Sphinx 3 will break at least Python, but likely other projects documentation.

It seems like we have the following options for the Python documentation:

• Stay at Sphinx forever
• Backport the ":c:struct:" and ":c:expr:" markups somehow in Sphinx 2 using our CPython Sphinx extensions
• Update Sphinx 3 to tolerate our "incorrect" documentation using :c:type: and :c:type:PyObject\* (invalid C syntax), maybe as an opt-in option
• Update Sphinx 2 to support Sphinx 3 new syntax: something like Python 2.7 which backported a few Python 3 features like b"bytes string" syntax

Example of issue: .. c:struct: MyStruct is required by Sphinx 3 to document a structure, since ``.. c:type: MyStructis now treated as an error. But with Sphinx 2,.. c:struct: MyStruct` section is simply ignored and the whole section miss from the HTML output.

cc @birkenfeld