Skip to content
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

PEP 12: Recommend and explain native RST hyperlinks (versus footnotes) #2302

Merged
merged 5 commits into from
Feb 17, 2022
Merged

PEP 12: Recommend and explain native RST hyperlinks (versus footnotes) #2302

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
6f583d2
PEP 12: Recommend and further explain using RST links, not footnotes
CAM-Gerlach Feb 4, 2022
b7a0aaa
PEP 1/12: Change name of References section to Footnotes in new PEPs
CAM-Gerlach Feb 4, 2022
42e7d3b
PEP 0, 1, 12: Update meta-PEPs to exemplify the current link guidance
CAM-Gerlach Feb 4, 2022
bdee439
PEP 12: Implement reviewer feedback and make further improvements
CAM-Gerlach Feb 16, 2022
be51524
PEP 12: Further reduce excess detail and examples in hyperlinks section
CAM-Gerlach Feb 16, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 10 additions & 12 deletions pep-0001.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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?
=================================

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

Expand Down
133 changes: 77 additions & 56 deletions pep-0012.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
========
Expand All @@ -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/>`_,
Copy link
Member

Choose a reason for hiding this comment

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

Can you also link the one on line 15 please?

Copy link
Member Author

Choose a reason for hiding this comment

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

I guess so, though it is a bit out of scope here.

as well as via a link at the bottom of each PEP.


Rationale
Expand Down Expand Up @@ -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/
Comment on lines -140 to -146
Copy link
Member

Choose a reason for hiding this comment

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

I only skimmed #2130, but I didn't see a copyright discussion -- there are a few PEPs licenced under the OPL (437, 483, 551, 578, 3145). For some authors there may be issues with PD/CC0, so noting the option exists may be useful?

Personally I am fine with PD (having released the code in this repo to it) -- and even better if I missed the dicussion & all good, but better safe than sorry & all that!

Copy link
Member Author

Choose a reason for hiding this comment

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

An option doesn't exist; all PEPs must be dual-licensed CC0 and "PD" (which is effectively the same as just licensing CC0, which in turn is a public domain declaration) per PEP 1 as implemented in #1117 per the discussion with PSF legal in #123 ; the lack of a corresponding update to PEP 12 was presumably an oversight. The OPL (which itself is an ambiguous acronym, as it could refer to either the Open Content License or the Open Publication License, two different licenses) is an obsolete, ambiguous, incompatible and likely legally flawed license; it would be strongly preferable to get those old PEPs relicensed, but that is entirely out of scope here.

Copy link
Member

Choose a reason for hiding this comment

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

Ahh, thanks for the links -- important that this gets updated, then.

A

- 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``).
Expand Down Expand Up @@ -438,43 +434,73 @@ 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:

.. code-block:: rst

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:
Comment on lines +451 to +456
Copy link
Member

Choose a reason for hiding this comment

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

Is it worth giving so much detail on how to write a link or to link to the reST docs at https://docutils.sourceforge.io/docs/user/rst/quickref.html#indirect-hyperlink-targets and provide the examples?

Same below for the other link styles.

Copy link
Member

Choose a reason for hiding this comment

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

I agree -- I'd suggest most of this section could be replaced with a pointer to the Docutils reference, perhaps excepting not to use raw URLs and to prefer HTTPS.

I'd go so far as to remove the examples, too.

Copy link
Member Author

@CAM-Gerlach CAM-Gerlach Feb 16, 2022 •
edited
Loading

Choose a reason for hiding this comment

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

My initial thought as well was just to point to the docutils reference or similar for the details, but:

  • The other sections all explicitly describe how to use their syntax elements without reference to docutils, so we should be consistent (might be worth revising, but out of scope here)
  • The docutils quickref doesn't actually explicitly discuss or provide examples for several of the things discussed here and commonly used/misused in PEPs, including indirect references of the form used here, multi-word link targets or the necessity of the space between the text and <, while the docutils full reference has a much higher level of comprehensive detail, much of which is not relevant here
  • This section contains a number of PEP-specific recommendations and guidance, such as where to put link targets, where and why to prefer different forms, and when to use anonymous references; the examples are tailored to PEPs; and the section is carefully organized to structure the key information in a logical and accessible manner for a PEP writer, rather than scattered all about.

So, my preference would be to keep it as-is, following the general status quo, and consider offloading the RST syntax details more generally in a potential future PR (after discussion on an issue). But if its overly lengthy, we could slim down some bits, like the rendered form for the different ways of specifying links.

Copy link
Member

Choose a reason for hiding this comment

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

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.

Copy link
Member Author

Choose a reason for hiding this comment

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

I see, thanks for the historical background @brettcannon . I agree it would likely be a good idea to slim down the detailed reST syntax descriptions in PEP 12 to just a brief summary and/or any PEP-specific guidance, and link to the relevant docutils/Sphinx guides and documentation for the rest, rather than belaboring the PEP with such details that are described elsewhere.

That said, that's a distinct and more expansive change than just updating the existing descriptions of how to use hyperlinks and footnotes (as is the scope of #2130 that this resolves) and something we should probably discuss in a separate issue first to make sure we're all in agreement and decide on a consistent approach to this throughout the PEP before going ahead with it.

For now, I've reverted the addition of all the "renders as" example blocks and their associated text for the hyperlinks section, along with an extra paragraph and the explanation and examples of numbered footnotes. I suggest we go ahead and merge this with those changes for now, so the PEP accurately reflects the current recommendations for links/references as agreed on in #2130 (and so I can move ahead with #2266), and I can open a new issue for us to discuss and decide upon the approach to take with PEP 12 moving forward, and implement that once consensus is reached. Does that sound good to you?

Copy link
Member

Choose a reason for hiding this comment

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

SGTM

Copy link
Member Author

Choose a reason for hiding this comment

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

Thanks! Opened as #2337


In this paragraph, we refer to the `Python web site`_.
.. code-block:: rst

Visit the `website <https://www.python.org/>`__ for more.

An explicit target provides the URL. Put targets in a References
section at the end of the PEP, or immediately after the reference.
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
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:
Expand All @@ -497,47 +523,42 @@ 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.
.. [#TeXbook] Donald Knuth's *The TeXbook*, pages 195 and 196.

References
==========
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.

Expand Down Expand Up @@ -631,27 +652,27 @@ 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
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:[email protected]?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
Expand Down
6 changes: 3 additions & 3 deletions pep-0012/pep-NNNN.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
10 changes: 5 additions & 5 deletions pep0/constants.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,14 +21,14 @@

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 = """ \
Expand Down
11 changes: 5 additions & 6 deletions pep2html.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -496,7 +496,7 @@ def apply(self):


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
Expand All @@ -510,14 +510,13 @@ def apply(self):
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):
Expand Down
13 changes: 6 additions & 7 deletions pep_sphinx_extensions/pep_processor/transforms/pep_footer.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,8 +9,8 @@
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,
Expand All @@ -30,10 +30,10 @@ def apply(self) -> None:
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:
Expand All @@ -43,7 +43,6 @@ def apply(self) -> None:
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":
Expand Down