Python documentation build broken

Hi, since the release of Docutils 0.18 today building Python documentation fails.

In CPython repository we have Sphinx pinned to 3.2.1, which has too loose requirement for Docutils version in install_requires – docutils>=0.12.

If I’m not mistaken the options now are:

  • pin down Docutils to version <0.18 in documentation requirements,
  • ask Sphinx maintainer, @tk0miya to release 3.2.2 with fixed Docutils requirement, update to it in documentation requirements,
  • update Sphinx to one of newer versions, which have Docutils requirement directive fixed (update of Sphinx would probably require changes in the documentation)

Example of failing build: Update translation from Transifex · python/python-docs-pl@9666e65 · GitHub.

bpo ticket: Issue 45618: Documentation builds fail with Sphinx 3.2.1 - Python tracker

cc @julien

For what it’s worth I’ve added a ticket and a pull request to fix the documentation build by pinning the Docutils version.

1 Like

Unfortunately, docutils-0.18 is incompatible with the Sphinx. At present, the latest release; Sphinx-4.2.0 does also not support it. So it’s difficult to release 3.2.2 ASAP. So I recommend you to pin docutils to 0.18.

BTW, since Sphinx-4.0, we’ve started to restrict the version of docutils to supported version. I believe there is no troubles for who uses the latest Sphinx. Therefore, the best way is upgrading Sphinx to the 4.0 or newer in the future. Then all pins can be removed.


The place to discuss this is the issue that @maciek opened: Issue 45618: Documentation builds fail with Sphinx 3.2.1 - Python tracker. The release team documentation expert, @julien, is on it.