iSharkFly-Open
/
python-peps
mirror of https://github.com/python/peps.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

PEP 12: Recommend reST hyperlinks over footnotes (#2302)

This commit is contained in:
CAM Gerlach 2022-02-17 11:26:37 -06:00 committed by GitHub
parent fc3eb216e3
commit 8e33abd30f
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
6 changed files with 107 additions and 90 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

22
pep-0001.txt
View File

@ -423,7 +423,6 @@ to development practices and other details. The precise process followed in
these cases will depend on the nature and purpose of the PEP being updated.
What belongs in a successful PEP?
=================================
@ -510,7 +509,8 @@ Each PEP should have the following parts/sections:
ready for consideration are complete and reduces people duplicating
prior discussion.
12. References -- A collection of URLs used as references through the PEP.
12. Footnotes -- A collection of footnotes cited in the PEP, and
a place to list non-inline hyperlink targets.
13. Copyright/license -- Each new PEP must be placed under a dual license of
public domain and CC0-1.0-Universal_ (see this PEP for an example).
@ -780,22 +780,20 @@ Resources:
* `Python Developer's Guide <https://devguide.python.org/>`_
References and Footnotes
========================
Footnotes
=========
.. [1] This historical record is available by the normal git commands
for retrieving older revisions, and can also be browsed via HTTP here:
https://github.com/python/peps
for retrieving older revisions, and can also be browsed
`on GitHub <https://github.com/python/peps>`__.
.. [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
in the `PEPs repo README
<https://github.com/python/peps/blob/main/README.rst>`__.
.. _.github/CODEOWNERS:
https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners
.. _.github/CODEOWNERS: https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners
.. _issue tracker:
https://bugs.python.org/
.. _issue tracker: https://bugs.python.org/
.. _CC0-1.0-Universal: https://choosealicense.com/licenses/cc0-1.0/

135
pep-0012.rst
View File

@ -12,7 +12,7 @@ Post-History: 30-Aug-2002
.. note::
For those who have written a PEP before, there is a template_
(which is included as a file in the PEPs repository).
(which is included as a file in the `PEPs repository`_).
Abstract
========
@ -26,8 +26,9 @@ Note: if you are reading this PEP via the web, you should first grab
the text (reStructuredText) source of this PEP in order to complete
the steps below. **DO NOT USE THE HTML FILE AS YOUR TEMPLATE!**
The source for this (or any) PEP can be found in the PEPs repository,
viewable on the web at https://github.com/python/peps/ .
The source for this (or any) PEP can be found in the
`PEPs repository <https://github.com/python/peps/>`_,
as well as via a link at the bottom of each PEP.
Rationale
@ -137,13 +138,8 @@ directions below.
prohibition of tab characters and the indentation requirements.
See "Suggested Sections" below for a template of sections to include.
- Update your References and Copyright section. Usually you'll place
your PEP into the public domain, in which case just leave the
Copyright section alone. Alternatively, you can use the `Open
Publication License`__, but public domain is still strongly
preferred.
__ http://www.opencontent.org/openpub/
- Update your Footnotes section, listing any footnotes and
non-inline link targets referenced by the text.
- Leave the Emacs stanza at the end of this file alone, including the
formfeed character ("^L", or ``\f``).
@ -438,24 +434,52 @@ Hyperlinks
----------
When referencing an external web page in the body of a PEP, you should
include the title of the page in the text, with either an inline
hyperlink reference to the URL or a footnote reference (see
`Footnotes`_ below). Do not include the URL in the body text of the
PEP.
include the title of the page or a suitable description in the text, with
either an inline hyperlink or a separate explicit target with the URL.
Do not include bare URLs in the body text of the PEP, and use HTTPS
links wherever available.
Hyperlink references use backquotes and a trailing underscore to mark
up the reference text; backquotes are optional if the reference text
is a single word. For example::
is a single word. For example, to reference a hyperlink target named
``Python website``, you would write:
In this paragraph, we refer to the `Python web site`_.
.. code-block:: rst
An explicit target provides the URL. Put targets in a References
section at the end of the PEP, or immediately after the reference.
In this paragraph, we refer to the `Python website`_.
If you intend to only reference a link once, and want to define it inline
with the text, insert the link into angle brackets (``<>``) after the text
you want to link, but before the closing backtick, with a space between the
text and the opening backtick. You should also use a double-underscore after
the closing backtick instead of a single one, which makes it an anonymous
reference to avoid conflicting with other target names. For example:
.. code-block:: rst
Visit the `website <https://www.python.org/>`__ for more.
If you want to use one link multiple places with different linked text,
or want to ensure you don't have to update your link target names when
changing the linked text, include the target name within angle brackets
following the text to link, *with an underscore after the target name
but before the closing angle bracket* (or the link **will not work**).
For example:
.. code-block:: rst
For further examples, see the `documentation <pydocs_>`_.
An explicit target provides the URL. Put targets in the Footnotes section
at the end of the PEP, or immediately after the paragraph with the reference.
Hyperlink targets begin with two periods and a space (the "explicit
markup start"), followed by a leading underscore, the reference text,
a colon, and the URL (absolute or relative)::
a colon, and the URL.
.. _Python web site: http://www.python.org/
.. code-block:: rst
.. _Python web site: https://www.python.org/
.. _pydocs: https://docs.python.org/
The reference text and the target text must match (although the match
is case-insensitive and ignores differences in whitespace). Note that
@ -463,18 +487,20 @@ the underscore trails the reference text but precedes the target text.
If you think of the underscore as a right-pointing arrow, it points
*away* from the reference and *toward* the target.
The same mechanism can be used for internal references. Every unique
section title implicitly defines an internal hyperlink target. We can
make a link to the Abstract section like this::
Internal and PEP/RFC Links
--------------------------
The same mechanism as hyperlinks can be used for internal references.
Every unique section title implicitly defines an internal hyperlink target.
We can make a link to the Abstract section like this:
.. code-block:: rst
Here is a hyperlink reference to the `Abstract`_ section. The
backquotes are optional since the reference text is a single word;
we can also just write: Abstract_.
Footnotes containing the URLs from external targets will be generated
automatically at the end of the References section of the PEP, along
with footnote references linking the reference text to the footnotes.
To refer to PEPs or RFCs, always use the ``:pep:`` and ``:rfc:`` roles,
never hardcoded URLs.
For example:
@ -497,46 +523,41 @@ that for you.
Footnotes
---------
Footnote references consist of a left square bracket, a number, a
right square bracket, and a trailing underscore:
Footnote references consist of a left square bracket, a label, a
right square bracket, and a trailing underscore.
Instead of a number, use a label of the
form "#word", where "word" is a mnemonic consisting of alphanumerics
plus internal hyphens, underscores, and periods (no whitespace or
other characters are allowed).
For example:
.. code-block:: rst
This sentence ends with a footnote reference [1]_.
Refer to The TeXbook [#TeXbook]_ for more information.
which renders as
Refer to The TeXbook [#TeXbook]_ for more information.
Whitespace must precede the footnote reference. Leave a space between
the footnote reference and the preceding word.
Use footnotes for additional notes, explanations and caveats, as well as
for references to books and other sources not readily available online.
Native reST hyperlink targets or inline hyperlinks in the text should be
used in preference to footnotes for including URLs to online resources.
Footnotes begin with ".. " (the explicit
markup start), followed by the footnote marker (no underscores),
followed by the footnote body. For example:
.. code-block:: rst
References
==========
.. [1] Note that the footnote reference is a numbered one.
.. [2] Donald Knuth's *The TeXbook*, pages 195 and 196.
During the course of developing your PEP, you may have to add, remove,
and rearrange footnote references, possibly resulting in mismatched
references, obsolete footnotes, and confusion. Auto-numbered
footnotes allow more freedom. Instead of a number, use a label of the
form "#word", where "word" is a mnemonic consisting of alphanumerics
plus internal hyphens, underscores, and periods (no whitespace or
other characters are allowed). For example:
.. code-block:: rst
Refer to The TeXbook [#TeXbook]_ for more information.
References
==========
.. [#TeXbook] Donald Knuth's *The TeXbook*, pages 195 and 196.
which renders as
.. [#TeXbook] Donald Knuth's *The TeXbook*, pages 195 and 196.
Footnotes and footnote references will be numbered automatically, and
the numbers will always match.
@ -631,15 +652,15 @@ thoroughness, please see:
* `A ReStructuredText Primer`__, a gentle introduction.
__ http://docutils.sourceforge.net/docs/rst/quickstart.html
__ https://docutils.sourceforge.io/docs/user/rst/quickstart.html
* `Quick reStructuredText`__, a users' quick reference.
__ http://docutils.sourceforge.net/docs/rst/quickref.html
__ https://docutils.sourceforge.io/docs/user/rst/quickref.html
* `reStructuredText Markup Specification`__, the final authority.
__ http://docutils.sourceforge.net/spec/rst/reStructuredText.html
__ https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html
The processing of reStructuredText PEPs is done using Docutils_. If
you have a question or require assistance with reStructuredText or
@ -647,11 +668,11 @@ Docutils, please `post a message`_ to the `Docutils-users mailing
list`_. The `Docutils project web site`_ has more information.
.. _Docutils:
.. _Docutils project web site: http://docutils.sourceforge.net/
.. _Docutils project web site: https://docutils.sourceforge.io/
.. _post a message:
mailto:docutils-users@lists.sourceforge.net?subject=PEPs
.. _Docutils-users mailing list:
http://docutils.sf.net/docs/user/mailing-lists.html#docutils-users
https://docutils.sourceforge.io/docs/user/mailing-lists.html#docutils-users
Copyright

6
pep-0012/pep-NNNN.rst
View File

@ -75,10 +75,10 @@ Open Issues
[Any points that are still being decided/discussed.]
References
==========
Footnotes
=========
[A collection of URLs used as references through the PEP.]
[A collection of footnotes cited in the PEP, and a place to list non-inline hyperlink targets.]
Copyright

10
pep0/constants.py
View File

@ -21,14 +21,14 @@ Created: 13-Jul-2000
intro = """\
This PEP contains the index of all Python Enhancement Proposals,
known as PEPs. PEP numbers are assigned by the PEP editors[1_], and
once assigned are never changed. The version control history [2_] of
the PEP texts represent their historical record.
known as PEPs. PEP numbers are :pep:`assigned <1#pep-editors>` by the
PEP editors, and once assigned are never changed.
The `version control history`_ of the PEP texts represent
their historical record.
"""
references = """\
.. [1] PEP 1: PEP Purpose and Guidelines
.. [2] View PEP history online: https://github.com/python/peps
.. _version control history: https://github.com/python/peps
"""
footer = """ \

11
pep2html.py
View File

@ -496,7 +496,7 @@ class PEPHeaders(Transform):
class PEPFooter(Transform):
"""Remove the References section if it is empty when rendered."""
"""Remove the References/Footnotes section if it is empty when rendered."""
# Set low priority so ref targets aren't removed before they are needed
default_priority = 999
@ -510,14 +510,13 @@ class PEPFooter(Transform):
for section in reversed(self.document):
if not isinstance(section, nodes.section):
continue
title_words = section[0].astext().lower().split()
if 'references' in title_words:
# Remove references section if there are no displayed
# footnotes (it only has title & link target nodes)
title_words = {*section[0].astext().lower().split()}
if {"references", "footnotes"} & title_words:
# Remove references/footnotes sections if there is no displayed
# content (i.e. they only have title & link target nodes)
if all(isinstance(ref_node, (nodes.title, nodes.target))
for ref_node in section):
section.parent.remove(section)
break
class PEPReader(standalone.Reader):

13
pep_sphinx_extensions/pep_processor/transforms/pep_footer.py
View File

@ -9,8 +9,8 @@ from docutils import transforms
class PEPFooter(transforms.Transform):
"""Footer transforms for PEPs.
- Removes the References section if it is empty when rendered.
- Creates a link to the (GitHub) source text.
- Remove the References/Footnotes section if it is empty when rendered.
- Create a link to the (GitHub) source text.
Source Link:
Create the link to the source file from the document source path,
@ -30,10 +30,10 @@ class PEPFooter(transforms.Transform):
for section in reversed(self.document[0]):
if not isinstance(section, nodes.section):
continue
title_words = section[0].astext().lower().split()
if "references" in title_words:
# Remove references section if there are no displayed
# footnotes (it only has title & link target nodes)
title_words = {*section[0].astext().lower().split()}
if {"references", "footnotes"} & title_words:
# Remove references/footnotes sections if there is no displayed
# content (i.e. they only have title & link target nodes)
to_hoist = []
types = set()
for node in section:
@ -43,7 +43,6 @@ class PEPFooter(transforms.Transform):
if types <= {nodes.title, nodes.target}:
section.parent.extend(to_hoist)
section.parent.remove(section)
break
# Add link to source text and last modified date
if pep_source_path.stem != "pep-0000":