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 <toonarmycapt...@hotmail.com> 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: python-dev-requ...@python.org <python-dev-requ...@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-requ...@python.org > > You can reach the person managing the list at > python-dev-ow...@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 <c...@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.ga69...@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 <c...@cskk.id.au> > > ------------------------------ > > Date: Sun, 13 Sep 2020 20:51:19 -0700 > From: Guido van Rossum <gu...@python.org> > Subject: [Python-Dev] Re: docs: I'd like new features to references > their PEPs > To: Cameron Simpson <c...@cskk.id.au> > Cc: Python-Dev <python-dev@python.org> > 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 <c...@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 <<a href=3D"mailt= > o:c...@cskk.id.au">c...@cskk.id.au</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 <c...@cskk.id.au> > Subject: [Python-Dev] Re: docs: I'd like new features to references > their PEPs > To: Guido van Rossum <gu...@python.org> > Cc: Python-Dev <python-dev@python.org> > Message-ID: <20200914050731.ga45...@cskk.homeip.net> > Content-Type: text/plain; charset=us-ascii > Message: 3 > > On 13Sep2020 20:51, Guido van Rossum <gu...@python.org> wrote: > >On Sun, Sep 13, 2020 at 8:12 PM Cameron Simpson <c...@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 <c...@cskk.id.au> > > ------------------------------ > > Date: Mon, 14 Sep 2020 01:16:00 -0400 > From: Ned Deily <n...@python.org> > Subject: [Python-Dev] Re: docs: I'd like new features to references > their PEPs > To: Cameron Simpson <c...@cskk.id.au> > Cc: Python-Dev <python-dev@python.org> > Message-ID: <ccd5d596-44eb-41f5-91f6-15bf1a066...@python.org> > Content-Type: text/plain; charset=us-ascii > Message: 4 > > On Sep 14, 2020, at 01:07, Cameron Simpson <c...@cskk.id.au> wrote: > > On 13Sep2020 20:51, Guido van Rossum <gu...@python.org> wrote: > >> On Sun, Sep 13, 2020 at 8:12 PM Cameron Simpson <c...@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 > n...@python.org -- [] > > ------------------------------ > > Date: Mon, 14 Sep 2020 19:25:57 +1000 > From: Cameron Simpson <c...@cskk.id.au> > Subject: [Python-Dev] Re: docs: I'd like new features to references > their PEPs > To: Ned Deily <n...@python.org> > Cc: Python-Dev <python-dev@python.org> > Message-ID: <20200914092557.ga40...@cskk.homeip.net> > Content-Type: text/plain; charset=us-ascii > Message: 5 > > On 14Sep2020 01:16, Ned Deily <n...@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 <c...@cskk.id.au> > > ------------------------------ > > Subject: Digest Footer > > _______________________________________________ > Python-Dev mailing list -- python-dev@python.org > To unsubscribe send an email to python-dev-le...@python.org > https://mail.python.org/mailman3/lists/python-dev.python.org/ > > > ------------------------------ > > End of Python-Dev Digest, Vol 206, Issue 24 > ******************************************* > _______________________________________________ > Python-Dev mailing list -- python-dev@python.org > To unsubscribe send an email to python-dev-le...@python.org > https://mail.python.org/mailman3/lists/python-dev.python.org/ > Message archived at > https://mail.python.org/archives/list/python-dev@python.org/message/PH7G4SZTWH3AJB5WGUXRJQLQTAASRKNI/ > Code of Conduct: http://python.org/psf/codeofconduct/
signature.asc
Description: Message signed with OpenPGP
_______________________________________________ Python-Dev mailing list -- python-dev@python.org To unsubscribe send an email to python-dev-le...@python.org https://mail.python.org/mailman3/lists/python-dev.python.org/ Message archived at https://mail.python.org/archives/list/python-dev@python.org/message/AQ2HDJHOINNWPBI4JCGJ2F7MN5JSGWYI/ Code of Conduct: http://python.org/psf/codeofconduct/
