Linking to a PEP for the historical record is fine, but let’s please make it clear that the PEP is both not the documentation for any feature, and may indeed be out of date. PEPs are deliberately not updated as features evolve.
Cheers, -Barry > On Sep 14, 2020, at 09:38, David Antonini <[email protected]> wrote: > > 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. > > <Outlook-Google IT .png> <Outlook-Google IT .png> > > From: [email protected] <[email protected]> > Sent: Monday, September 14, 2020 11:00 AM > To: [email protected] <[email protected]> > Subject: Python-Dev Digest, Vol 206, Issue 24 > > Send Python-Dev mailing list submissions to > [email protected] > > 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 > [email protected] > > You can reach the person managing the list at > [email protected] > > 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 <[email protected]> > Subject: [Python-Dev] docs: I'd like new features to references their > PEPs > To: Python-Dev <[email protected]> > Message-ID: <[email protected]> > 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 <[email protected]> > > ------------------------------ > > Date: Sun, 13 Sep 2020 20:51:19 -0700 > From: Guido van Rossum <[email protected]> > Subject: [Python-Dev] Re: docs: I'd like new features to references > their PEPs > To: Cameron Simpson <[email protected]> > Cc: Python-Dev <[email protected]> > Message-ID: > <cap7+vjjfsrdspbhks3r6xvb4p3+oxomru9gswimdfdvcekv...@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 <[email protected]> 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 <<a href=3D"mailt= > o:[email protected]">[email protected]</a>> 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'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 "New in version 3.4", it also sai= > d <br> > "specified by PEP424 [link]", 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'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 f= > eature was added (assuming there's a "versionadded" note), bu= > t that'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'm sure that's not the only case. But all in all I li= > ke the idea of linking to the PEP from the "versionadded" or &quo= > t;versionchanged" 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 <[email protected]> > Subject: [Python-Dev] Re: docs: I'd like new features to references > their PEPs > To: Guido van Rossum <[email protected]> > Cc: Python-Dev <[email protected]> > Message-ID: <[email protected]> > Content-Type: text/plain; charset=us-ascii > Message: 3 > > On 13Sep2020 20:51, Guido van Rossum <[email protected]> wrote: > >On Sun, Sep 13, 2020 at 8:12 PM Cameron Simpson <[email protected]> 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 <[email protected]> > > ------------------------------ > > Date: Mon, 14 Sep 2020 01:16:00 -0400 > From: Ned Deily <[email protected]> > Subject: [Python-Dev] Re: docs: I'd like new features to references > their PEPs > To: Cameron Simpson <[email protected]> > Cc: Python-Dev <[email protected]> > Message-ID: <[email protected]> > Content-Type: text/plain; charset=us-ascii > Message: 4 > > On Sep 14, 2020, at 01:07, Cameron Simpson <[email protected]> wrote: > > On 13Sep2020 20:51, Guido van Rossum <[email protected]> wrote: > >> On Sun, Sep 13, 2020 at 8:12 PM Cameron Simpson <[email protected]> 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 > [email protected] -- [] > > ------------------------------ > > Date: Mon, 14 Sep 2020 19:25:57 +1000 > From: Cameron Simpson <[email protected]> > Subject: [Python-Dev] Re: docs: I'd like new features to references > their PEPs > To: Ned Deily <[email protected]> > Cc: Python-Dev <[email protected]> > Message-ID: <[email protected]> > Content-Type: text/plain; charset=us-ascii > Message: 5 > > On 14Sep2020 01:16, Ned Deily <[email protected]> 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 <[email protected]> > > ------------------------------ > > Subject: Digest Footer > > _______________________________________________ > Python-Dev mailing list -- [email protected] > To unsubscribe send an email to [email protected] > https://mail.python.org/mailman3/lists/python-dev.python.org/ > > > ------------------------------ > > End of Python-Dev Digest, Vol 206, Issue 24 > ******************************************* > _______________________________________________ > Python-Dev mailing list -- [email protected] > To unsubscribe send an email to [email protected] > https://mail.python.org/mailman3/lists/python-dev.python.org/ > Message archived at > https://mail.python.org/archives/list/[email protected]/message/PH7G4SZTWH3AJB5WGUXRJQLQTAASRKNI/ > Code of Conduct: http://python.org/psf/codeofconduct/
signature.asc
Description: Message signed with OpenPGP
_______________________________________________ Python-Dev mailing list -- [email protected] To unsubscribe send an email to [email protected] https://mail.python.org/mailman3/lists/python-dev.python.org/ Message archived at https://mail.python.org/archives/list/[email protected]/message/AQ2HDJHOINNWPBI4JCGJ2F7MN5JSGWYI/ Code of Conduct: http://python.org/psf/codeofconduct/
