René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"PEP 12: Refer to canonical docutils quickref/reference instead of duplicating description of reST syntax","articleBody":"Spawned out of [a discussion](https://github.com/python/peps/pull/2302#discussion_r799737762) with @brettcannon and @AA-Turner on #2302 .\r\n\r\nPEP 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](https://docutils.sourceforge.io/docs/user/rst/quickstart.html), [quickref](https://docutils.sourceforge.io/docs/user/rst/quickref.html) and [specification](https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html).\r\n\r\nAs @brettcannon mentions there, this is largely a historical artifact of the fact that \r\n\r\n\u003e 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.\r\n\r\nWhile 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.\r\n\r\nFurthermore, 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).\r\n\r\nTherefore, 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:\r\n\r\n* Slimming down the lengthy descriptions and examples of generic reST syntax that duplicate material in the reST primer, quickref and specification\r\n* Linking and referring readers to the relevant section(s) in the reST primer, quickref and spec, as appropriate\r\n* 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)\r\n\r\nWe 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.\r\n\r\nThoughts?","author":{"url":"https://github.com/CAM-Gerlach","@type":"Person","name":"CAM-Gerlach"},"datePublished":"2022-02-17T01:09:22.000Z","interactionStatistic":{"@type":"InteractionCounter","interactionType":"https://schema.org/CommentAction","userInteractionCount":4},"url":"https://github.com/2337/peps/issues/2337"}