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

[CAM-Gerlach]

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?

[CAM-Gerlach]

As a corollary, a broader issue I've noticed is a somewhat unclear separation between PEP 1 and PEP 12, with a number of details of the format leaking from the latter into the former (which would be nice to decouple from abstract process, and more concretely from the more governance-y aspects of that PEP that make me leery of proposing even mundane changes to even the purely technical/editorial parts without high-level review).

What's more, some things, like the header spec and the list of suggested sections, are duplicated two or even three places between PEP 1, PEP 12 and the standalone template, often with significant differences in content or simply drifting out of sync (which came up in at least one PR lately, where the three say different things about whether the email address can/should/must be listed for PEP authors, sponsors and delegates).

While this issue doesn't address this concern directly, it does substantially reduce the length and tighten the focus of PEP 12 on the specifics of the PEP format (rather than a guide to generic RST syntax), which lends itself well to a future PR potentially consolidating the other purely technical details of the PEP format (primarily, the headers and the suggested sections) currently split/duplicated between PEP 1 and PEP 12 into PEP 12 as well, allowing PEP 1 to focus more cleanly on the PEP purpose, process, governance and other higher-level concerns.

This would both benefit PEP authors and reviewers (as it makes it easier and more logical to find the information specific to their needs while avoiding conflicting guidance from different sources), and us PEP editors (by improving maintainability, reducing duplication of effort and more cleanly separating purely technical from potentially process/governance changes that might need higher-level review). If and when we have consensus on this issue and I go ahead with a PR, I can open another to consider these ideas further, if there's interest.

[encukou]

Perhaps link to Sphinx's copy instead? https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
And there's another copy the devguide: https://devguide.python.org/documenting/#rst-primer

[CAM-Gerlach]

Thanks!

Perhaps link to Sphinx's copy instead? https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html

We definitely want to do this if and when PEP 676 is implemented, since its a lot friendlier and better organized, IMO, but since it discusses a number of Sphinx-specific constructs and behaviors, I retained the docutils reST references for now to avoid user confusion and use of docutils-incompatible syntax, roles and directives.

And there's another copy the devguide: https://devguide.python.org/documenting/#rst-primer

Good point, though it seems like that copy is fairly brief, is mostly focused on covering more docs-relevant roles and directives and doesn't mention a number of reST constructs cited and used here; similarly, it includes a fair amount of Sphinx-specific advice that doesn't (yet) apply here, so long as we need to maintain docutils compat.

[CAM-Gerlach]

This was discussed at the December Python Docs Community meeting, and it was generally agreed that moving ahead with this would be a good first step, alongside the equivalent python/devguide#1000 . I plan to go ahead with a PR soon-ish.