Clarify best practices with ref target labels in docs
@CAM-Gerlach 已经在做这个了。
开始于 2022年8月3日。
评估
这个 Issue 还没有评估数据。
描述
On python/cpython#94636 , specifically https://github.com/python/cpython/pull/94636#discussion_r934008442 , @ezio-melotti , @erlend-aasland and I discussed that that it might be helpful to clarify in the devguide some additional guidance related to reference target labels in the Cross-linking markup section.
Specifically, it could mention that whenever possible, the existing ref target should be left place (either instead of or addition to adding a new one) when sections are changed or moved, since it ensures any inbound internal or Intersphinx references don't break or need to be changed, as well as any external links that anchor (provided that it wasn't moved to a different page without a redirection).
Also, it could provide a guideline and examples on how ref labels should be "namespaced" to avoid conflicts, i.e. by the module name for library docs, or the page name elsewhere, documenting existing (if not always consistent) convention.
If we agree this would be helpful, I can submit a PR on this once #916 is merged.
- 主要语言
- Python
- 星标
- 2.1k
- 派生
- 1k
- 平均合并
- 2 天 12 小时
- 30 天内合并 PR
- 12
贡献指南
从这里开始
- 先读完整个 Issue，再读项目的贡献指南。
- 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
- Fork 仓库，在一个分支上完成修改。
- 提交 Pull Request，并在描述里引用这个 Issue 编号。
python/devguide 的其他 Issue
-
type-feature
难度 2/5 1-3 小时 新手友好度 68/100
-
type-feature
难度 2/5 1-3 小时 新手友好度 68/100
-
topic-building python type-feature
难度 2/5 1-3 小时 新手友好度 65/100
-
needs: decision topic-test type-bug
难度 2/5 1-3 小时 新手友好度 78/100
-
topic-dev process type-feature
难度 2/5 1-3 小时 新手友好度 62/100
相似的 Issue
-
link-check link-check:sphinx-theme
难度 2/5 1-3 小时 新手友好度 72/100
-
难度 2/5 1-3 小时 新手友好度 65/100
qgis/QGIS-Documentation#11275 ·
-
bug priority:normal ready-for-dev
难度 2/5 1-3 小时 新手友好度 88/100
OpenHands/extensions#626 · 1 条评论 ·
-
难度 1/5 1 小时以内 新手友好度 90/100
CSCfi/sd-search-api#39 ·
-
难度 1/5 1 小时以内 新手友好度 90/100