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 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.

From: python-dev-request@python.org Sent: Monday, September 14, 2020 11:00 AM To: 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 Subject: [Python-Dev] docs: I'd like new features to references their PEPs To: Python-Dev 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

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

Date: Sun, 13 Sep 2020 20:51:19 -0700 From: Guido van Rossum Subject: [Python-Dev] Re: docs: I'd like new features to references their PEPs To: Cameron Simpson Cc: Python-Dev Message-ID: 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 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-c...

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

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

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 presized allocation operations) lets an implementor write something more 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.

...

...

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>

<div>--Guido = van Rossum (http://python.org/~guido" target=3D"_blank">python.o= rg/~guido</a>)</div><div><span>Pronouns</span>: = he/him </i>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><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 Subject: [Python-Dev] Re: docs: I'd like new features to references their PEPs To: Guido van Rossum Cc: Python-Dev Message-ID: <20200914050731.GA45157@cskk.homeip.net> Content-Type: text/plain; charset=us-ascii Message: 3

On 13Sep2020 20:51, Guido van Rossum 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 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

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

Date: Mon, 14 Sep 2020 01:16:00 -0400 From: Ned Deily Subject: [Python-Dev] Re: docs: I'd like new features to references their PEPs To: Cameron Simpson Cc: Python-Dev Message-ID: Content-Type: text/plain; charset=us-ascii Message: 4

On Sep 14, 2020, at 01:07, Cameron Simpson wrote:

...

On 13Sep2020 20:51, Guido van Rossum 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 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 Subject: [Python-Dev] Re: docs: I'd like new features to references their PEPs To: Ned Deily Cc: Python-Dev Message-ID: <20200914092557.GA40543@cskk.homeip.net> Content-Type: text/plain; charset=us-ascii Message: 5

On 14Sep2020 01:16, Ned Deily 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

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

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/

0 0

Reply

attachment

• signature.asc

Sign in to reply online Use email software

Brandt Bucher

7:24 p.m.

New subject: docs: I'd like new features to references their PEPs

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.

0 0

Reply

Sign in to reply online Use email software

Brett Cannon

9 p.m.

New subject: docs: I'd like new features to references their PEPs

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 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/

0 0

Reply

attachment

• attachment.htm

Sign in to reply online Use email software

Guido van Rossum

9:14 p.m.

New subject: docs: I'd like new features to references their PEPs

On Mon, Sep 14, 2020 at 12:08 PM Brett Cannon 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-c...

0 0

Reply

attachment

• attachment.htm

Sign in to reply online Use email software