Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Jan 21, 2022
Merged

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
a92ab04
Use the explicit `:rfc:` role instead of implicit inlining
AA-Turner Jan 2, 2022
8296711
Use the explicit `:pep:` role instead of implicit inlining
AA-Turner Dec 23, 2021
99bef6b
fix markup for rogue grave accents
AA-Turner Jan 2, 2022
5e7e3f5
Turn off the inliner for PEP and RST references
AA-Turner Jan 2, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
61 changes: 25 additions & 36 deletions pep-0001.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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.
Expand Down Expand Up @@ -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. ::

Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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
Expand All @@ -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:

Expand Down Expand Up @@ -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)
Copy link
Member

@merwok merwok Jan 20, 2022 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The previous system was a bit weird with its footnotes instead of inline links, but one good point was that you could see the linked PEP title without following the link.

Since we are in the PEP repo (with the data on hand without network requests needed), could the code be adapted so that the PEP number and title is used as HTML title attribute on the generated links?

(Maybe not if it’s Sphinx handling it and not any repo-specific code…)
Edit: I found PEPRole thanks to the nice new build process doc!

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fantastic suggestion! That would be really nice and something I've been wanting for a while myself. (To note, with manual footnotes you still have to click the link to go to the footnote to see it of course, it just doesn't generate a HTTP request)

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Will have a look, seems pretty easy.


.. [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:
Expand Down
10 changes: 5 additions & 5 deletions pep-0002.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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.


Expand Down Expand Up @@ -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
Expand Down
4 changes: 2 additions & 2 deletions pep-0003.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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).

Expand Down
4 changes: 2 additions & 2 deletions pep-0004.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down Expand Up @@ -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.

Expand Down
11 changes: 2 additions & 9 deletions pep-0006.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down Expand Up @@ -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
Expand All @@ -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
=========

Expand Down
9 changes: 1 addition & 8 deletions pep-0007.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down Expand Up @@ -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
=========

Expand Down
Loading