Repository navigation
Infra: errors blocking migration towards docutils 0.22+ #4924
Description
Activity
We've been generally been trying to use refs prefixed with the PEP number to make them unique, for example:
❯ rg "^\.\. _pep\d\d\d" peps/pep-0387.rst 117:.. _pep387-soft-deprecation: peps/pep-0825/appendix-variant-json-schema.rst 3:.. _pep825-variant-json-schema: peps/pep-0793.rst 277:.. _pep793-token: 396:.. _pep793-api-summary: 471:.. _pep793-porting-notes: 576:.. _pep793-shim: 624:.. _pep793-example: peps/pep-0803.rst 882:.. _pep803-rejected-ideas: 910:.. _pep803-no-shim: peps/pep-0820.rst 168:.. _pep820-rationale: 466:.. _pep820-nested-tables: 583:.. _pep820-hard-deprecations: peps/pep-0749.rst 425:.. _pep749-metaclasses: peps/pep-0798.rst 218:.. _pep798-genexpsemantics: 381:.. _pep798-reference: 412:.. _pep798-examples: 653:.. _pep798-functionargs: 705:.. _pep798-moregeneral: 734:.. _pep798-alternativegenexpsemantics: 917:.. _pep798-appendix-yieldfrom: peps/pep-0827.rst 315:.. _pep827-unpack-kwargs: 365:.. _pep827-extended-callables-prereq: 548:.. _pep827-unpacked: 598:.. _pep827-boolean-ops: 677:.. _pep827-members: 742:.. _pep827-init-field: 787:.. _pep827-generic-callable: 818:.. _pep827-update-class: 836:.. _pep827-lifting: 866:.. _pep827-rt-support: 908:.. _pep827-qb-impl: 1020:.. _pep827-fastapi-impl: 1066:.. _pep827-init-impl: 1184:.. _pep827-numpy-impl: 1238:.. _pep827-ts-utils: 1318:.. _pep827-callable-rationale: 1344:.. _pep827-generic-callable-rationale: 1700:.. _pep827-less_syntax: 1777:.. _pep827-strict-kinds: peps/pep-0763.rst 284:.. _pep763-appendix-a: peps/pep-0728.rst 409:.. _pep728-inheritance-read-only: 681:.. _pep728-type-narrowing:
Reacted by Carol Willing@hugovk the pep-named references might be a good lead, but I did some investigation and it's sometimes two references within the same doc. I will try to make proper fixes once #4087 is done (made a draft #4926 for after the required fixes are all merged and done).
@willingc it's nothing much, just trying to give something back to the Python community
Reacted by Hugo van Kemenade, Carol Willing and arturkokurc1-progReacted by Carol Willing and Hugo van Kemenade- changed the title
[-]Infra: errors blocking migration towards Sphinx 9+ and docutils 0.22[/-][+]Infra: errors blocking migration towards docutils 0.22+[/+]on Aug 17, 2026 I think a single PR should be fine, as it's only 7 PEPs.
Reacted by Bartosz Sokorski
Following the work in #4087, I have decided to investigate possible issues with going further, towards docutils 0.22+. The following are extracts from the errors failing the build process (tested on Sphinx 9.1.0 and docutils 0.22.4). I have error logs with full tracebacks and more details available if needed.
Errors
peps/pep-0554.rst:29: (ERROR/3) Indirect hyperlink target (id="concurrency") refers to target "concurrency", which is a duplicate, and cannot be used as a unique reference.peps/pep-0683.rst:476: (ERROR/3) Indirect hyperlink target (id="documentation") refers to target "documentation", which is a duplicate, and cannot be used as a unique reference.peps/pep-0426.rst:748: (ERROR/3) Duplicate target name, cannot be used as a unique reference: "extras".peps/pep-0653.rst:722: (WARNING/2) Footnote content expected.peps/pep-0827.rst:1963: (WARNING/2) Footnote content expected.peps/pep-0697.rst:250: (ERROR/3) Indirect hyperlink target (id="reference-implementation") refers to target "reference implementation", which is a duplicate, and cannot be used as a unique reference.peps/pep-0791.rst:163: (ERROR/3) Indirect hyperlink target (id="id1") refers to target "motivation", which is a duplicate, and cannot be used as a unique reference.All of those errors are coming from docutils, not from Sphinx, but they are hard-failing the parallel Sphinx builds.
CC @hugovk
EDIT: After investigation, only docutils is blocked. Sphinx 9 works fine.