python / python/peps

Infra: errors blocking migration towards docutils 0.22+

未关闭
#4,924 6 条评论 1 个 reaction 已指派 0 人 在 GitHub 查看

还没有人认领这个 Issue。

infra
主要语言
reStructuredText
星标
5k
派生
1.8k
平均合并
2 天 4 小时
30 天内合并 PR
25

描述

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.

贡献指南

打开贡献指南

从这里开始

  1. 先读完整个 Issue,再读项目的贡献指南。
  2. 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
  3. Fork 仓库,在一个分支上完成修改。
  4. 提交 Pull Request,并在描述里引用这个 Issue 编号。

调研方向

首先使用 Sphinx 9.1.0 和 docutils 0.22.4 重现并行 Sphinx 构建,然后检查 peps/pep-0554.rst、peps/pep-0683.rst、peps/pep-0426.rst、peps/pep-0653.rst、peps/pep-0827.rst、peps/pep-0697.rst 和 peps/pep-0791.rst 中报告的位置。完成的标准是,列出的 docutils 错误和警告不再导致构建硬失败,同时保留 PEP 内容。

由索引模型根据 Issue 内容生成。

评估

领域
build-system, documentation
Issue 类型
缺陷
难度
3/5
预计耗时
1-2 天
活跃度
活跃
描述清晰度
基本清楚
新手友好度
55/100

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。