Infra: errors blocking migration towards docutils 0.22+
Nobody has claimed this yet.
- Dominant language
- reStructuredText
- Stars
- 5k
- Forks
- 1.8k
- Avg merge
- 2d 4h
- Merged PRs (30d)
- 25
Description
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.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reproducing the parallel Sphinx build with Sphinx 9.1.0 and docutils 0.22.4, then inspect the reported locations in peps/pep-0554.rst, pep-0683.rst, pep-0426.rst, pep-0653.rst, pep-0827.rst, pep-0697.rst, and pep-0791.rst. Done means the listed docutils errors and warnings no longer hard-fail the build while preserving the PEP content.
Written by the indexing model from the issue text.
Assessment
- Domain
- build-system, documentation
- Issue type
- Bug
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 55/100