python / python/devguide

reST Primer duplicates the Sphinx version; should link to it instead

未关闭
#1,000 7 条评论 2 个 reaction 已指派 1 人 在 GitHub 查看

@CAM-Gerlach 已经在做这个了。

开始于 2022年7月31日。

type-bug type-feature
主要语言
Python
星标
2.1k
派生
1k
平均合并
2 天 12 小时
30 天内合并 PR
12

描述

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

贡献指南

打开贡献指南

从这里开始

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

评估

这个 Issue 还没有评估数据。

把新 issue 发到你的邮箱

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