python / python/peps

PEP 12: Refer to canonical docutils quickref/reference instead of duplicating description of reST syntax

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

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

开始于 2022年2月17日。

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

描述

Spawned out of a discussion with @brettcannon and @AA-Turner on #2302 .

PEP 12 (PEP-0012) contains a large amount of detailed explanations and examples of generic reST syntax, directives and usage that in large part duplicates the content of the reST Primer, quickref and specification.

As @brettcannon mentions there, this is largely a historical artifact of the fact that

The detailed comments are from a time when we had to teach people how to write reST for a PEP since PEPs predate the format. Since reST is now so old, I don't think it's important long-term.

While it is potentially helpful to PEP writers to keep everything in one PEP-focused document, and the maintenance cost for us to retain it is not so high, to follow the existing conventions we will need to continue to update all of the detailed explanations and examples (rather than just the PEP-specific content) to reflect changes in practice over time (some of which are likely the case already), changes due to PEP 676 if/when it is approved, and other future changes in reST, docutils and Sphinx.

Furthermore, it might better serve most readers to focus on high-level recommendations and notes specific to the formatting of PEPs, our extensions/custom rules, stylistic conventions, and best practices; while linking to (instead of duplicating) the more comprehensive and authoritative resources on reST syntax. Most PEP writers are likely pretty familiar with the basics (if not all the details) of reST already, and if not will be well- (or even better-) served by handy direct links to the tutorial, examples and full reference for each main element in question (rather than just links to the top-level resources at the bottom of the PEP).

Therefore, for each of the major generic reST syntax elements described (i.e. the various headings under the top-level "ReStructuredText PEP Formatting Requirements" section, e.g. hyperlinks, tables, etc), I propose:

  • Slimming down the lengthy descriptions and examples of generic reST syntax that duplicate material in the reST primer, quickref and specification
  • Linking and referring readers to the relevant section(s) in the reST primer, quickref and spec, as appropriate
  • Retaining a concise summary and highlighting any guidance, conventions, recommendations and information specific to PEPs and the PEP format (or otherwise not found in the linked resources)

We could also consider mentioning the main reST resources in the "Resources" section nearer the top, e.g. as part of the introduction of the reST formatting section, so readers can start be e.g. reading the primer or browsing the quickref rather than jumping straight into the PEP-specific elements.

Thoughts?

贡献指南

打开贡献指南

从这里开始

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

评估

这个 Issue 还没有评估数据。

把新 issue 发到你的邮箱

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