classification
Title: Documentation builds fail with Sphinx 3.2.1
Type: crash Stage: patch review
Components: Documentation Versions: Python 3.11, Python 3.10, Python 3.9, Python 3.8, Python 3.7, Python 3.6
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: Maciej Olko, docs@python, erlendaasland, lukasz.langa, mdk, miss-islington, ned.deily, pablogsal
Priority: release blocker Keywords: patch

Created on 2021-10-26 22:34 by Maciej Olko, last changed 2021-10-31 20:51 by miss-islington.

Pull Requests
URL Status Linked Edit
PR 29230 merged Maciej Olko, 2021-10-26 22:55
PR 29240 merged miss-islington, 2021-10-27 14:21
PR 29241 merged ned.deily, 2021-10-27 14:34
PR 29245 merged ned.deily, 2021-10-27 16:53
PR 29256 merged Maciej Olko, 2021-10-27 22:28
Messages (11)
msg405060 - (view) Author: Maciej Olko (Maciej Olko) * Date: 2021-10-26 22:34
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.

Example of failing build: https://github.com/python/python-docs-pl/runs/4009459257.

My suggestion is to pin down docutils in docs requirements.
msg405061 - (view) Author: Maciej Olko (Maciej Olko) * Date: 2021-10-26 22:45
The pin can be removed after bumping Sphinx to at least 3.5.4, which introduced upper limit for docutils version.

https://github.com/sphinx-doc/sphinx/commit/9263eea38379822e053c67ad1d17036d724c5e41
msg405099 - (view) Author: Ned Deily (ned.deily) * (Python committer) Date: 2021-10-27 14:21
New changeset bcee6aa31550cfecdc3acecbd0e4447bb0051887 by m-aciek in branch 'main':
bpo-45618: Fix documentation build by pinning Docutils version to 0.17.1 (GH-29230)
https://github.com/python/cpython/commit/bcee6aa31550cfecdc3acecbd0e4447bb0051887
msg405101 - (view) Author: Ned Deily (ned.deily) * (Python committer) Date: 2021-10-27 14:37
New changeset 2b7b7c7320cd856df5439afc3c984873678c27d8 by Miss Islington (bot) in branch '3.10':
bpo-45618: Fix documentation build by pinning Docutils version to 0.17.1 (GH-29230) (GH-29240)
https://github.com/python/cpython/commit/2b7b7c7320cd856df5439afc3c984873678c27d8
msg405102 - (view) Author: Ned Deily (ned.deily) * (Python committer) Date: 2021-10-27 15:04
New changeset 30c1f18ee62cef301e18488b80b4d329290f7b95 by Ned Deily in branch '3.9':
[3.9] bpo-45618: Fix documentation build by pinning Docutils version to 0.17.1 (GH-29230) (GH-29241)
https://github.com/python/cpython/commit/30c1f18ee62cef301e18488b80b4d329290f7b95
msg405118 - (view) Author: Ned Deily (ned.deily) * (Python committer) Date: 2021-10-27 17:57
All of the open branches are affected by this since we also have to build documentation for security-fix-only branches when releases. PRs for 3.7 and 3.6 forthcoming.
msg405125 - (view) Author: Maciej Olko (Maciej Olko) * Date: 2021-10-27 21:19
For what it's worth I have just successfully built documentation on 3.7 and 3.6 branches locally.  It looks like Sphinx 2.3.1 used there doesn't use this part of docutils API that have changed recently.

Sphinx 2.3.1 has requirement of "docutils>=0.12", just like 3.2.1.

We can pin docutils version to current (0.18) "just in case" to prevent a breakage in the future or do nothing – maybe it won't break – maybe the docutils API used is narrow enough.
msg405134 - (view) Author: Maciej Olko (Maciej Olko) * Date: 2021-10-27 22:07
It occurs that the documentation builds without warnings on most recent Sphinx -- version 4.2.0. Probably we should bump the version in 3.11, 3.10 and 3.9 to 4.2.0. That would enable us to remove the pin on docutils.
msg405135 - (view) Author: Maciej Olko (Maciej Olko) * Date: 2021-10-27 22:09
I'm sorry for the confusion. I might have make more checking on my side before proposing a fix.
msg405229 - (view) Author: Łukasz Langa (lukasz.langa) * (Python committer) Date: 2021-10-28 19:08
New changeset f2407144347fafcd69c2ade41b5d9c3fb07b59ef by Ned Deily in branch '3.8':
[3.9] bpo-45618: Fix documentation build by pinning Docutils version to 0.17.1 (GH-29230) (GH-29241) (GH-29245)
https://github.com/python/cpython/commit/f2407144347fafcd69c2ade41b5d9c3fb07b59ef
msg405420 - (view) Author: miss-islington (miss-islington) Date: 2021-10-31 20:51
New changeset 14a4fce457033412278ca9a056787db424310dc3 by m-aciek in branch 'main':
bpo-45618: Update Sphinx version used to build the documentation to 4.2.0 (GH-29256)
https://github.com/python/cpython/commit/14a4fce457033412278ca9a056787db424310dc3
History
Date User Action Args
2021-10-31 20:51:42miss-islingtonsetmessages: + msg405420
2021-10-28 19:08:46lukasz.langasetmessages: + msg405229
2021-10-27 22:28:11Maciej Olkosetpull_requests: + pull_request27520
2021-10-27 22:09:10Maciej Olkosetmessages: + msg405135
2021-10-27 22:07:05Maciej Olkosetmessages: + msg405134
2021-10-27 21:19:23Maciej Olkosetmessages: + msg405125
2021-10-27 17:57:03ned.deilysetmessages: + msg405118
versions: + Python 3.6, Python 3.7, Python 3.8
2021-10-27 16:53:21ned.deilysetpull_requests: + pull_request27509
2021-10-27 15:04:53ned.deilysetmessages: + msg405102
2021-10-27 14:37:25ned.deilysetmessages: + msg405101
2021-10-27 14:34:25ned.deilysetpull_requests: + pull_request27504
2021-10-27 14:21:50miss-islingtonsetnosy: + miss-islington
pull_requests: + pull_request27503
2021-10-27 14:21:38ned.deilysetnosy: + ned.deily
messages: + msg405099
2021-10-27 07:20:17erlendaaslandsetnosy: + erlendaasland
2021-10-27 03:55:31ned.deilysetpriority: normal -> release blocker
nosy: + pablogsal, lukasz.langa, mdk

versions: + Python 3.9
2021-10-26 22:55:45Maciej Olkosetkeywords: + patch
stage: patch review
pull_requests: + pull_request27493
2021-10-26 22:45:06Maciej Olkosetmessages: + msg405061
2021-10-26 22:39:21Maciej Olkosetversions: + Python 3.11
2021-10-26 22:39:10Maciej Olkosetversions: - Python 3.6, Python 3.7, Python 3.8, Python 3.9, Python 3.11
2021-10-26 22:34:59Maciej Olkocreate