reST Primer duplicates the Sphinx version; should link to it instead
@CAM-Gerlach 已經在處理了。
開始於 2022年7月31日。
評估
這個 Issue 還沒有評估資料。
描述
Similar to PEP 12, the reST primer in the devguide duplicates the same information in the Sphinx reST primer, along with some bits specific to its particular context.
In fact, unlike PEP 12, they are mostly word for word identical and thus clearly derive from a common source, with the Sphinx version being close to a strict superset of the CPython version, containing some additional and updated sections but also still mentioning many CPython-specific conventions (e.g. section heading format).
This near-duplication is clearly not very DRY, and has several main problems:
- Additions, improvements and updates/changes to one are not reflected in the other. Clearly, the more appropriate place for this is the Sphinx docs as it is generally applicable to all Sphinx users, and indeed they seem to have been kept much more up to date there, and it also links the full reST reference for each section for readers looking for more information.
- Readers already familiar with reST or just looking for the CPython-specific bits must either dig through each section, or may skip it entirely and miss them
Therefore, I propose for the Devguide reST primer:
- Recommending and linking the Sphinx reST primer at the top of the Devguide reST primer section
- Linking each top-level devguide reST primer section to the corresponding Sphinx section via Intersphinx
- Eliminating all but the CPython-specific guidance/convention/recommendations in each section
There are also some non-specific bits that could be trimmed from the Additional Markup Constructs section, and each role/directive should be linked to its canonical full Sphinx documentation if present, but that can be addressed separately on a case by case basis.
If we agree this is desirable, I'm willing to take this on, unless @ezio-melotti would prefer to do it.
Somewhat related: python/devguide#916
- 主要語言
- 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
-
難度 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
-
難度 2/5 1-3 小時 新手友好度 68/100
StevenBlack/hosts#3255 ·