Re: docs: I'd like new features to references their PEPs
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]<https://www.youracclaim.com/badges/95b4438c-8719-4e89-ad79-6c45c3c8481f/public_url> [Google IT Automation with Python Professional Certificate] <https://www.youracclaim.com/badges/75926d2a-6313-4c43-9f76-82bc8a3ed4b0/public_url> ________________________________ 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 <<a href=3D"mailt= o:cs@cskk.id.au">cs@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=
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=
<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= 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:
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
On Sun, Sep 13, 2020 at 8:12 PM Cameron Simpson <cs@cskk.id.au> wrote: 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:
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
On Sun, Sep 13, 2020 at 8:12 PM Cameron Simpson <cs@cskk.id.au> wrote: 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:.
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 *******************************************
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 <toonarmycaptain@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-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 <<a href=3D"mailt= o:cs@cskk.id.au">cs@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=
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=
<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= 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:
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
On Sun, Sep 13, 2020 at 8:12 PM Cameron Simpson <cs@cskk.id.au> wrote: 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:
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
On Sun, Sep 13, 2020 at 8:12 PM Cameron Simpson <cs@cskk.id.au> wrote: 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:.
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 ******************************************* _______________________________________________ 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/ Message archived at https://mail.python.org/archives/list/python-dev@python.org/message/PH7G4SZT... Code of Conduct: http://python.org/psf/codeofconduct/
Agreed. To prevent the docs from going stale, the "Originally proposed in :pep:`XXX`." wording should probably be used for *all* of the new links, not just the ones that are currently out-of-date. Depending on the scope of these changes, we could also just consider adding a new ".. pepadded:: XXX" directive for reuse and consistency.
I would honestly argue that if the language spec doesn't clearly explain the motivation behind something then that should be directly addressed rather than link back to the PEP. We already have an issue with people misinterpreting the PEPs as documentation, trying to keep them up-to-date, etc. and I think explicitly linking back for historical context isn't beneficial enough to warrant the overhead. On Mon, Sep 14, 2020 at 10:30 AM Brandt Bucher <brandtbucher@gmail.com> wrote:
Agreed. To prevent the docs from going stale, the "Originally proposed in :pep:`XXX`." wording should probably be used for *all* of the new links, not just the ones that are currently out-of-date.
Depending on the scope of these changes, we could also just consider adding a new ".. pepadded:: XXX" directive for reuse and consistency. _______________________________________________ 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/ Message archived at https://mail.python.org/archives/list/python-dev@python.org/message/2R4JJSJT... Code of Conduct: http://python.org/psf/codeofconduct/
On Mon, Sep 14, 2020 at 12:08 PM Brett Cannon <brett@python.org> wrote:
I would honestly argue that if the language spec doesn't clearly explain the motivation behind something then that should be directly addressed rather than link back to the PEP. We already have an issue with people misinterpreting the PEPs as documentation, trying to keep them up-to-date, etc. and I think explicitly linking back for historical context isn't beneficial enough to warrant the overhead.
Hm, I think that's a little strong. There are plenty of PEP references in the existing docs. (For example, the importlib docs have a half page of PEP references under "See also". :-) I also think that the language spec and library reference aren't always the best place to explain the *motivation* -- they are for users who want to know what to do. So a link to a PEP seems to make more sense than duplicating the information (unless the library/language docs need to contradict a PEP, of course). -- --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/>
participants (5)
-
Barry Warsaw -
Brandt Bucher -
Brett Cannon -
David Antonini -
Guido van Rossum