Title: adding PEP references to documentation
Type: Stage: patch review
Components: Documentation Versions:
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: cameron, docs@python
Priority: normal Keywords: patch

Created on 2020-09-14 22:49 by cameron, last changed 2020-09-16 03:26 by cameron.

Pull Requests
URL Status Linked Edit
PR 22269 open cameron, 2020-09-16 03:26
Messages (3)
msg376914 - (view) Author: Cameron Simpson (cameron) * Date: 2020-09-14 22:49
Add rationale for __length_hint__ and link to PEP 424, per the discussion here:

Once the phrasing and directives are agreed, continue to chase other references in the docs.

This will produce multiple small PRs, possibly one per PEP as chased.


I intend to amend the "New in version V." lines to become "New in version V, originally specified by PEPNNN." with a link to the PEP on "PEPNNN". I'm tempted to make "version V" also a link to its Whats New page; that will make for a bit more visual noise but seems pertinent.

The other thing I'd like to consider is a _single sentence_ in the docs identifying the main motivating use case for the feature. The __length_hint__ docs are a prime example here - the purpose of the feature is not mentioned, merely its semantics. While a feature can be used for many purposes, knowing why it was introduces brings a lot of cognitive benefit to the reader.
msg376967 - (view) Author: Cameron Simpson (cameron) * Date: 2020-09-16 00:01
Re the possible change to "New in version V." text, my proposal there is the make this become:

    New in :ref:`version V <whatsnew-V>`.

by modifying the definitions in sphinxdomains/ from:

versionlabels = {
    'versionadded':   _('New in version %s'),
    'versionchanged': _('Changed in version %s'),
    'deprecated':     _('Deprecated since version %s'),


versionlabels = {
    'versionadded':   _('New in :ref:`version %s <whatsnew-%s>`'),
    'versionchanged': _('Changed in :ref:`version %s <whatsnew-%s`'),
    'deprecated':     _('Deprecated since :ref:`version %s <whatsnew-%s>`'),

and adding a:

    :: _whatsnew-3.7:

to Doc/whatsnew/3.7.rst and likewise for the other whatsnew files.

That requires a change to both the docs and sphinx, and is independent of the PEP reference additions. I'll make a distinct PR for this, unrelated to the other PRs.

In an ideal world we could be more precise by using one of the _whatsnew37-feature anchors where they are present, but I don't see how to integrate that into the versionadded directives (absent something quite intrusive). The above change makes a docs-wide sweep immediately without additional work.
msg376968 - (view) Author: Cameron Simpson (cameron) * Date: 2020-09-16 00:02
Argh. I bet that additional %s above won't work :-(
Date User Action Args
2020-09-16 03:26:47cameronsetkeywords: + patch
stage: patch review
pull_requests: + pull_request21324
2020-09-16 00:02:32cameronsetmessages: + msg376968
2020-09-16 00:01:36cameronsetmessages: + msg376967
2020-09-14 22:49:01cameroncreate