If the API has changed significantly since the PEP, simply stating that could be useful eg "as originally specified in `PEP x`, although the API and typical usage have evolved since originally implemented". Or "as orginally specified in `PEP x`, although that API was later changed because `insert terrible namespace clash or other reoganisation`. This would inform readers that information/code snippets found elsewhere might be targeting various degrees of different API/usages. 

The PEP link/this detail could be in a superscript linkPEP or note2 that appears upon mouseover, or similarly obscured to minimise reading interruption, if such explanation is considered useful, but breaks the flow of the doc more than desirable.

I feel like the Docs Working Group might have some productive discussion on such topics, when it gets started.

Google IT Support Professional Certificate   Google IT Automation with Python Professional Certificate

From: python-dev-request@python.org <python-dev-request@python.org>
Sent: Monday, September 14, 2020 11:00 AM
To: python-dev@python.org <python-dev@python.org>
Subject: Python-Dev Digest, Vol 206, Issue 24
 
Send Python-Dev mailing list submissions to
        python-dev@python.org

To subscribe or unsubscribe via the World Wide Web, visit
        https://mail.python.org/mailman3/lists/python-dev.python.org/
or, via email, send a message with subject or body 'help' to
        python-dev-request@python.org

You can reach the person managing the list at
        python-dev-owner@python.org

When replying, please edit your Subject line so it is more specific
than "Re: Contents of Python-Dev digest..."

Today's Topics:

   1. docs: I'd like new features to references their PEPs
      (Cameron Simpson)
   2. Re: docs: I'd like new features to references their PEPs
      (Guido van Rossum)
   3. Re: docs: I'd like new features to references their PEPs
      (Cameron Simpson)
   4. Re: docs: I'd like new features to references their PEPs
      (Ned Deily)
   5. Re: docs: I'd like new features to references their PEPs
      (Cameron Simpson)


----------------------------------------------------------------------

Date: Mon, 14 Sep 2020 12:50:24 +1000
From: Cameron Simpson <cs@cskk.id.au>
Subject: [Python-Dev] docs: I'd like new features to references their
        PEPs
To: Python-Dev <python-dev@python.org>
Message-ID: <20200914025024.GA69157@cskk.homeip.net>
Content-Type: text/plain; charset=us-ascii
Message: 1

So, today I noticed __length_hint__, and then operator.length_hint. 
Neither mentions its design purpose, only its specification. And while
that is minimally enough, knowing the purpoe (size estimation for use by
presized allocation operations) lets an implementor write something more
appropriate.

While it'd be nice to have a short sentence with the provoking rationale
for the feature in the docs, it would also be nice to reference the PEP.

As a concrete example, for __length_hint__ and operator.length_hint, I
wish that in addition to saying "New in version 3.4", it also said
"specified by PEP424 [link]", since I had to go find that with a search
engine to understand the rationale.

Would PRs with such patches be welcome?

Cheers,
Cameron Simpson <cs@cskk.id.au>

------------------------------

Date: Sun, 13 Sep 2020 20:51:19 -0700
From: Guido van Rossum <guido@python.org>
Subject: [Python-Dev] Re: docs: I'd like new features to references
        their PEPs
To: Cameron Simpson <cs@cskk.id.au>
Cc: Python-Dev <python-dev@python.org>
Message-ID:
        <CAP7+vJJFSRdSpbHks3r6xvB4P3+OXoMRu9gSwiMdFDVCekVWyw@mail.gmail.com>
Content-Type: multipart/alternative;
        boundary="0000000000006ee04305af3df322"
Message: 2

--0000000000006ee04305af3df322
Content-Type: text/plain; charset="UTF-8"

On Sun, Sep 13, 2020 at 8:12 PM Cameron Simpson <cs@cskk.id.au> wrote:

> So, today I noticed __length_hint__, and then operator.length_hint.
> Neither mentions its design purpose, only its specification. And while
> that is minimally enough, knowing the purpoe (size estimation for use by
> presized allocation operations) lets an implementor write something more
> appropriate.
>
> While it'd be nice to have a short sentence with the provoking rationale
> for the feature in the docs, it would also be nice to reference the PEP.
>
> As a concrete example, for __length_hint__ and operator.length_hint, I
> wish that in addition to saying "New in version 3.4", it also said
> "specified by PEP424 [link]", since I had to go find that with a search
> engine to understand the rationale.
>
> Would PRs with such patches be welcome?
>

Yeah, I think that's a reasonable idea, and I don't think it needs a news
item or bpo bug either. If you know there's a PEP you should be able to
find it through the what's new doc for the version where the feature was
added (assuming there's a "versionadded" note), but that's pretty indirect,
and people might not even think there could be a PEP.

A downside of linking to the PEP is that sometimes the PEP has an outdated
version of an API. For example asyncio has evolved quite a bit since PEP
3156 (some stuff in the PEP turned out not so hot), and I'm sure that's not
the only case. But all in all I like the idea of linking to the PEP from
the "versionadded" or "versionchanged" note.

--
--Guido van Rossum (python.org/~guido)
*Pronouns: he/him **(why is my pronoun here?)*
<http://feministing.com/2015/02/03/how-using-they-as-a-singular-pronoun-can-change-the-world/>

--0000000000006ee04305af3df322
Content-Type: text/html; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable

<div dir=3D"ltr"><div class=3D"gmail_quote"><div dir=3D"ltr" class=3D"gmail=
_attr">On Sun, Sep 13, 2020 at 8:12 PM Cameron Simpson &lt;<a href=3D"mailt=
o:cs@cskk.id.au">cs@cskk.id.au</a>&gt; wrote:<br></div><blockquote class=3D=
"gmail_quote" style=3D"margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(2=
04,204,204);padding-left:1ex">So, today I noticed __length_hint__, and then=
 operator.length_hint.=C2=A0 <br>
Neither mentions its design purpose, only its specification. And while <br>
that is minimally enough, knowing the purpoe (size estimation for use by <b=
r>
presized allocation operations) lets an implementor write something more <b=
r>
appropriate.<br>
<br>
While it&#39;d be nice to have a short sentence with the provoking rational=
e <br>
for the feature in the docs, it would also be nice to reference the PEP.<br=
>
<br>
As a concrete example, for __length_hint__ and operator.length_hint, I <br>
wish that in addition to saying &quot;New in version 3.4&quot;, it also sai=
d <br>
&quot;specified by PEP424 [link]&quot;, since I had to go find that with a =
search <br>
engine to understand the rationale.<br>
<br>
Would PRs with such patches be welcome?<br></blockquote><div><br></div><div=
>Yeah, I think that&#39;s a reasonable idea, and I don&#39;t think it needs=
 a news item or bpo bug either. If you know there&#39;s a PEP you should be=
 able to find it through the what&#39;s new doc for the version where the f=
eature was added (assuming there&#39;s a &quot;versionadded&quot; note), bu=
t that&#39;s pretty indirect, and people might not even think there could b=
e a PEP.</div><div><br></div><div>A downside of linking to the PEP is that =
sometimes the PEP has an outdated version of an API. For example asyncio ha=
s evolved quite a bit since PEP 3156 (some stuff in the PEP turned out not =
so hot), and I&#39;m sure that&#39;s not the only case. But all in all I li=
ke the idea of linking to the PEP from the &quot;versionadded&quot; or &quo=
t;versionchanged&quot; note.<br></div></div><br>-- <br><div dir=3D"ltr" cla=
ss=3D"gmail_signature"><div dir=3D"ltr"><div><div dir=3D"ltr"><div>--Guido =
van Rossum (<a href=3D"http://python.org/~guido" target=3D"_blank">python.o=
rg/~guido</a>)</div><div><i style=3D"font-family:Arial,Helvetica,sans-serif=
;font-size:small;font-weight:400;letter-spacing:normal;text-align:start;tex=
t-indent:0px;text-transform:none;white-space:normal;word-spacing:0px;backgr=
ound-color:rgb(255,255,255);color:rgb(136,136,136)"><span>Pronouns</span>: =
he/him </i><a href=3D"http://feministing.com/2015/02/03/how-using-they-as-a=
-singular-pronoun-can-change-the-world/" style=3D"color:rgb(17,85,204);font=
-family:Arial,Helvetica,sans-serif;font-size:small;font-style:normal;font-w=
eight:400;letter-spacing:normal;text-align:start;text-indent:0px;text-trans=
form:none;white-space:normal;word-spacing:0px;background-color:rgb(255,255,=
255)" target=3D"_blank"><i>(why is my=C2=A0<span>pronoun</span>=C2=A0here?)=
</i></a></div></div></div></div></div></div>

--0000000000006ee04305af3df322--

------------------------------

Date: Mon, 14 Sep 2020 15:07:31 +1000
From: Cameron Simpson <cs@cskk.id.au>
Subject: [Python-Dev] Re: docs: I'd like new features to references
        their PEPs
To: Guido van Rossum <guido@python.org>
Cc: Python-Dev <python-dev@python.org>
Message-ID: <20200914050731.GA45157@cskk.homeip.net>
Content-Type: text/plain; charset=us-ascii
Message: 3

On 13Sep2020 20:51, Guido van Rossum <guido@python.org> wrote:
>On Sun, Sep 13, 2020 at 8:12 PM Cameron Simpson <cs@cskk.id.au> wrote:
>> As a concrete example, for __length_hint__ and operator.length_hint,
>> I
>> wish that in addition to saying "New in version 3.4", it also said
>> "specified by PEP424 [link]", since I had to go find that with a search
>> engine to understand the rationale.
[...]
>A downside of linking to the PEP is that sometimes the PEP has an
>outdated
>version of an API. For example asyncio has evolved quite a bit since PEP
>3156 (some stuff in the PEP turned out not so hot), and I'm sure that's not
>the only case. But all in all I like the idea of linking to the PEP from
>the "versionadded" or "versionchanged" note.

Happy to use the term "originally specified by PEP424 [link]" :-)

I'll make some PRs. How to submit? Here, or a BPO or something?

Cheers,
Cameron Simpson <cs@cskk.id.au>

------------------------------

Date: Mon, 14 Sep 2020 01:16:00 -0400
From: Ned Deily <nad@python.org>
Subject: [Python-Dev] Re: docs: I'd like new features to references
        their PEPs
To: Cameron Simpson <cs@cskk.id.au>
Cc: Python-Dev <python-dev@python.org>
Message-ID: <CCD5D596-44EB-41F5-91F6-15BF1A066822@python.org>
Content-Type: text/plain;       charset=us-ascii
Message: 4

On Sep 14, 2020, at 01:07, Cameron Simpson <cs@cskk.id.au> wrote:
> On 13Sep2020 20:51, Guido van Rossum <guido@python.org> wrote:
>> On Sun, Sep 13, 2020 at 8:12 PM Cameron Simpson <cs@cskk.id.au> wrote:
>>> As a concrete example, for __length_hint__ and operator.length_hint,
>>> I
>>> wish that in addition to saying "New in version 3.4", it also said
>>> "specified by PEP424 [link]", since I had to go find that with a search
>>> engine to understand the rationale.
> [...]
>> A downside of linking to the PEP is that sometimes the PEP has an
>> outdated
>> version of an API. For example asyncio has evolved quite a bit since PEP
>> 3156 (some stuff in the PEP turned out not so hot), and I'm sure that's not
>> the only case. But all in all I like the idea of linking to the PEP from
>> the "versionadded" or "versionchanged" note.
> Happy to use the term "originally specified by PEP424 [link]" :-)
>
> I'll make some PRs. How to submit? Here, or a BPO or something?

My suggestion would be to open one BPO issue for "adding PEP references to documentation" and then creating PRs as needed against it.  As you probably know, the devguide has the details including for the inline markup role :pep:.

https://devguide.python.org/documenting/#rest-inline-markup

--
  Ned Deily
  nad@python.org -- []

------------------------------

Date: Mon, 14 Sep 2020 19:25:57 +1000
From: Cameron Simpson <cs@cskk.id.au>
Subject: [Python-Dev] Re: docs: I'd like new features to references
        their PEPs
To: Ned Deily <nad@python.org>
Cc: Python-Dev <python-dev@python.org>
Message-ID: <20200914092557.GA40543@cskk.homeip.net>
Content-Type: text/plain; charset=us-ascii
Message: 5

On 14Sep2020 01:16, Ned Deily <nad@python.org> wrote:
>> I'll make some PRs. How to submit? Here, or a BPO or something?
>
>My suggestion would be to open one BPO issue for "adding PEP references to documentation" and then creating PRs as needed against it.  As you probably know, the devguide has the details including for the inline markup role :pep:.
>
>https://devguide.python.org/documenting/#rest-inline-markup

Thanks Ned. - Cameron Simpson <cs@cskk.id.au>

------------------------------

Subject: Digest Footer

_______________________________________________
Python-Dev mailing list -- python-dev@python.org
To unsubscribe send an email to python-dev-leave@python.org
https://mail.python.org/mailman3/lists/python-dev.python.org/


------------------------------

End of Python-Dev Digest, Vol 206, Issue 24
*******************************************