Several PEPs: Use explicit :pep: and :rfc: roles (#2209)

Author: AA-Turner

pep-0001.txt

@@ -80,15 +80,15 @@ Python's Steering Council
 
 There are several references in this PEP to the "Steering Council" or "Council".
 This refers to the current members of the elected Steering Council described
-in PEP 13 [5]_, in their role as the final authorities on whether or not PEPs
+in :pep:`13`, in their role as the final authorities on whether or not PEPs
 will be accepted or rejected.
 
 
 Python's Core Developers
 ------------------------
 
 There are several references in this PEP to "core developers". This refers to
-the currently active Python core team members described in PEP 13 [5]_.
+the currently active Python core team members described in :pep:`13`.
 
 
 Python's BDFL
@@ -188,23 +188,23 @@ The standard PEP workflow is:
   "Informational", or "Process" as appropriate, and for the "Status:"
   field enter "Draft".  For full details, see `PEP Header Preamble`_.
 
-* Update `.github/CODEOWNERS` [7]_ such that any co-author(s) or sponsors
+* Update `.github/CODEOWNERS` [3]_ such that any co-author(s) or sponsors
   with write access to the `PEP repository`_ are listed for your new file.
   This ensures any future pull requests changing the file will be assigned
   to them.
 
 * Push this to your GitHub fork and submit a pull request.
 
 * The PEP editors review your PR for structure, formatting, and other
-  errors.  For a reST-formatted PEP, PEP 12 is provided as a template.
+  errors.  For a reST-formatted PEP, :pep:`12` is provided as a template.
   It also provides a complete introduction to reST markup that is used
   in PEPs.  Approval criteria are:
 
   * It sound and complete.  The ideas must make technical sense.  The
     editors do not consider whether they seem likely to be accepted.
   * The title accurately describes the content.
   * The PEP's language (spelling, grammar, sentence structure, etc.)
-    and code style (examples should match PEP 8 & PEP 7) should be
+    and code style (examples should match :pep:`8` & :pep:`7`) should be
     correct and conformant.  The PEP will be checked for formatting
     (plain text or reStructuredText) by Travis CI, and will not be
     approved until this passes.
@@ -283,16 +283,16 @@ The final authority for PEP approval is the Steering Council. However, whenever
 a new PEP is put forward, any core developer that believes they are suitably
 experienced to make the final decision on that PEP may offer to serve as
 the PEP-Delegate for that PEP, and they will then have the
-authority to approve (or reject) that PEP. 
+authority to approve (or reject) that PEP.
 
 The term "PEP-Delegate" is used under the Steering
 Council governance model. The PEP's designated decision maker,
 the "PEP-Delegate" with the Steering Council's support, is
 recorded in the "PEP-Delegate" field in the PEP's header. For
 PEPs written prior to the Steering Council's governance model, the field name
 "BDFL-Delegate" will still be kept.
-The terms PEP-Delegate and BDFL-Delegate may be used interchangeably in 
-discussion. PEP-Delegate is the preferred term under the Steering Council 
+The terms PEP-Delegate and BDFL-Delegate may be used interchangeably in
+discussion. PEP-Delegate is the preferred term under the Steering Council
 governance model.
 
 Individuals offering to serve as PEP-Delegate should notify the Steering
@@ -343,7 +343,7 @@ implementation, if applicable, must be solid and must not complicate
 the interpreter unduly.  Finally, a proposed enhancement must be
 "pythonic" in order to be accepted by the Steering Council.  (However,
 "pythonic" is an imprecise term; it may be defined as whatever is acceptable to
-the Steering Council.  This logic is intentionally circular.)  See PEP 2 [2]_
+the Steering Council.  This logic is intentionally circular.)  See :pep:`2`
 for standard library module acceptance criteria.
 
 Once a PEP has been accepted, the reference implementation must be
@@ -362,7 +362,7 @@ been included in a Python release*.
 Wherever possible, it is considered preferable to reduce the scope of a proposal
 to avoid the need to rely on the "Provisional" status (e.g. by deferring some
 features to later PEPs), as this status can lead to version compatibility
-challenges in the wider Python ecosystem. PEP 411 provides additional details
+challenges in the wider Python ecosystem. :pep:`411` provides additional details
 on potential use cases for the Provisional status.
 
 A PEP can also be assigned the status "Deferred".  The PEP author or an
@@ -400,7 +400,7 @@ deprecation process (which may require a new PEP providing the rationale for
 the deprecation).
 
 Some Informational and Process PEPs may also have a status of "Active"
-if they are never meant to be completed.  E.g. PEP 1 (this PEP).
+if they are never meant to be completed.  E.g. :pep:`1` (this PEP).
 
 
 PEP Maintenance
@@ -427,7 +427,7 @@ What belongs in a successful PEP?
 
 Each PEP should have the following parts/sections:
 
-1. Preamble -- RFC 822 style headers containing meta-data about the
+1. Preamble -- :rfc:`2822` style headers containing meta-data about the
    PEP, including the PEP number, a short descriptive title (limited
    to a maximum of 44 characters), the names, and optionally the
    contact info for each author, etc.
@@ -519,17 +519,18 @@ PEP Formats and Templates
 
 PEPs are UTF-8 encoded text files using the reStructuredText_ format.
 ReStructuredText_ allows for rich markup that is still quite easy to
-read, but also results in good-looking and functional HTML. PEP 12
-contains instructions and a template [4]_ for reStructuredText PEPs.
+read, but also results in good-looking and functional HTML. :pep:`12`
+contains instructions and a :pep:`template <12#suggested-sections>`
+for reStructuredText PEPs.
 
-The PEP text files are automatically converted to HTML [6]_ for easier
+The PEP text files are automatically converted to HTML [2]_ for easier
 `online reading <https://www.python.org/dev/peps/>`__.
 
 
 PEP Header Preamble
 ===================
 
-Each PEP must begin with an RFC 822 style header preamble.  The headers
+Each PEP must begin with an :rfc:`2822` style header preamble.  The headers
 must appear in the following order.  Headers marked with "*" are
 optional and are described below.  All other headers are required. ::
 
@@ -567,7 +568,7 @@ PEPs must use the mandated format above, and it is acceptable to
 change to this format when PEPs are updated.
 
 If there are multiple authors, each should be on a separate line
-following RFC 2822 continuation line conventions.  Note that personal
+following :rfc:`2822` continuation line conventions.  Note that personal
 email addresses in PEPs will be obscured as a defense against spam
 harvesters.
 
@@ -598,8 +599,8 @@ The Type header specifies the type of PEP: Standards Track,
 Informational, or Process.
 
 The format of a PEP is specified with a Content-Type header.  The
-acceptable values are "text/plain" for plaintext PEPs (see PEP 9 [3]_)
-and "text/x-rst" for reStructuredText PEPs (see PEP 12 [4]_).
+acceptable values are "text/plain" for plaintext PEPs (see :pep:`9`)
+and "text/x-rst" for reStructuredText PEPs (see :pep:`12`).
 reStructuredText is strongly preferred, but for backwards
 compatibility plain text is currently still the default if no
 Content-Type header is present.
@@ -709,11 +710,11 @@ For each new PEP that comes in an editor does the following:
 * The file name extension is correct (i.e. ``.rst``).
 
 * Ensure that everyone listed as a sponsor or co-author of the PEP who has write
-  access to the `PEP repository`_ is added to `.github/CODEOWNERS` [7]_.
+  access to the `PEP repository`_ is added to `.github/CODEOWNERS` [3]_.
 
 * Skim the PEP for obvious defects in language (spelling, grammar,
   sentence structure, etc.), and code style (examples should conform to
-  PEP 8 & PEP 7).  Editors may correct problems themselves, but are
+  :pep:`8` & :pep:`7`).  Editors may correct problems themselves, but are
   not required to do so.  (Text format is checked by Travis CI.)
 
 * If a project is portrayed as benefiting from or supporting the PEP, make sure
@@ -723,7 +724,7 @@ For each new PEP that comes in an editor does the following:
 
 If the PEP isn't ready, an editor will send it back to the author for
 revision, with specific instructions.  If reST formatting is a
-problem, ask the author(s) to use PEP 12 as a template and resubmit.
+problem, ask the author(s) to use :pep:`12` as a template and resubmit.
 
 Once the PEP is ready for the repository, a PEP editor will:
 
@@ -789,23 +790,11 @@ References and Footnotes
    for retrieving older revisions, and can also be browsed via HTTP here:
    https://github.com/python/peps
 
-.. [2] PEP 2, Procedure for Adding New Modules
-   (http://www.python.org/dev/peps/pep-0002)
-
-.. [3] PEP 9, Sample Plaintext PEP Template
-   (http://www.python.org/dev/peps/pep-0009)
-
-.. [4] PEP 12, Sample reStructuredText PEP Template
-   (http://www.python.org/dev/peps/pep-0012)
-
-.. [5] PEP 13, Python Language Governance
-   (http://www.python.org/dev/peps/pep-0013)
-
-.. [6] More details on the PEP rendering and publication process can be found
+.. [2] More details on the PEP rendering and publication process can be found
    in the PEPs repo README at
    https://github.com/python/peps/blob/main/README.rst
 
-.. [7] `CODEOWNERS` documentation
+.. [3] `CODEOWNERS` documentation
    (https://docs.github.com/en/github/creating-cloning-and-archiving-repositories/about-code-owners)
 
 .. _issue tracker:

pep-0002.txt

@@ -35,10 +35,10 @@ the library; things that are missing but should be added.
 
 New functionality is commonly added to the library in the form of new
 modules. This PEP will describe the procedure for the *addition* of
-new modules.  PEP 4 deals with procedures for deprecation of modules;
+new modules.  :pep:`4` deals with procedures for deprecation of modules;
 the *removal* of old and unused modules from the standard library.
 Finally there is also the issue of *changing* existing modules to make
-the picture of library evolution complete. PEP 3 and PEP 5 give some
+the picture of library evolution complete. :pep:`3` and :pep:`5` give some
 guidelines on this. The continued maintenance of existing modules is
 an integral part of the decision on whether to add a new module to the
 standard library.  Therefore, this PEP also introduces concepts
@@ -101,7 +101,7 @@ One or more maintainers shall step forward as PEP champion (the people
 listed in the Author field are the champions).  The PEP champion(s)
 shall be the initial head maintainer(s).
 
-As described in PEP 1, a standards track PEP should consist of a
+As described in :pep:`1`, a standards track PEP should consist of a
 design document and a reference implementation.  The library PEP
 differs from a normal standard track PEP in that the reference
 implementation should in this case always already have been written
@@ -126,7 +126,7 @@ This different requirement exists for the following reasons:
 
 Once the library PEP has been submitted for review, the integrators
 will then evaluate it.  The PEP will follow the normal PEP work flow
-as described in PEP 1.  If the PEP is accepted, they will work through
+as described in :pep:`1`.  If the PEP is accepted, they will work through
 the head maintainers to make the contribution ready for integration.
 
 
@@ -155,7 +155,7 @@ In the case where no head maintainer can be found (possibly because
 there are no maintainers left), the integrators will issue a call to
 the community at large asking for new maintainers to step forward.  If
 no one does, the integrators can decide to declare the contribution
-deprecated as described in PEP 4.
+deprecated as described in :pep:`4`.
 
 
 Open issues

pep-0003.txt

@@ -35,8 +35,8 @@ Original Guidelines
    out, say, what all the open Tkinter bugs are.
 
 2. If it's a minor feature request that you don't plan to address
-   right away, add it to PEP 42 or ask the owner to add it for you.
-   If you add the bug to PEP 42, mark the bug as "feature request",
+   right away, add it to :pep:`42` or ask the owner to add it for you.
+   If you add the bug to :pep:`42`, mark the bug as "feature request",
    "later", and "closed"; and add a comment to the bug saying that
    this is the case (mentioning the PEP explicitly).
 

pep-0004.txt

@@ -56,7 +56,7 @@ For modules existing in both Python 2.7 and Python 3.5
 In order to facilitate writing code that works in both Python 2 & 3
 simultaneously, any module that exists in both Python 3.5 and
 Python 2.7 will not be removed from the standard library until
-Python 2.7 is no longer supported as specified by PEP 373. Exempted
+Python 2.7 is no longer supported as specified by :pep:`373`. Exempted
 from this rule is any module in the idlelib package as well as any
 exceptions granted by the Python development team.
 
@@ -293,7 +293,7 @@ Deprecated modules
 Deprecation of modules removed in Python 3.0
 ============================================
 
-PEP 3108 lists all modules that have been removed from Python 3.0.
+:pep:`3108` lists all modules that have been removed from Python 3.0.
 They all are documented as deprecated in Python 2.6, and raise a
 DeprecationWarning if the -3 flag is activated.
 

pep-0006.txt

@@ -143,7 +143,7 @@ the maintenance branch, or else mark the patch in the commit message.
 
 In addition, anyone from the Python community is free to suggest
 patches for inclusion. Patches may be submitted specifically for
-bugfix releases; they should follow the guidelines in PEP 3 [2]_. In
+bugfix releases; they should follow the guidelines in :pep:`3`. In
 general, though, it's probably better that a bug in a specific release
 also be fixed on the HEAD as well as the branch.
 
@@ -194,7 +194,7 @@ sticking with a strict bug fix policy.
 Following feedback from the BDFL and others, the draft PEP was written
 containing an expanded bugfix release cycle that permitted any
 previous major release to obtain patches and also relaxed the strict
-bug fix requirement (mainly due to the example of PEP 235 [3]_, which
+bug fix requirement (mainly due to the example of :pep:`235`, which
 could be argued as either a bug fix or a feature).
 
 Discussion then mostly moved to python-dev, where BDFL finally issued
@@ -213,13 +213,6 @@ References
 .. [1] http://www.tcl.tk/cgi-bin/tct/tip/28.html
 
 
-.. [2] PEP 3, Guidelines for Handling Bug Reports, Hylton
-    (http://www.python.org/dev/peps/pep-0003/)
-
-.. [3] PEP 235, Import on Case-Insensitive Platforms, Peters
-    (http://www.python.org/dev/peps/pep-0235/)
-
-
 Copyright
 =========
 

pep-0007.txt

@@ -15,7 +15,7 @@ Introduction
 
 This document gives coding conventions for the C code comprising the C
 implementation of Python.  Please see the companion informational PEP
-describing style guidelines for Python code [1]_.
+describing :pep:`style guidelines for Python code <8>`.
 
 Note, rules are there to be broken.  Two good reasons to break a
 particular rule:
@@ -217,13 +217,6 @@ Documentation Strings
   not all do; the MSVC compiler is known to complain about this.
 
 
-References
-==========
-
-.. [1] PEP 8, "Style Guide for Python Code", van Rossum, Warsaw
-       (http://www.python.org/dev/peps/pep-0008)
-
-
 Copyright
 =========