[Python-Dev] Re: docs: I'd like new features to references their PEPs

2020-09-15 Thread Cameron Simpson
On 14Sep2020 18:17, Terry Reedy wrote: >On 9/14/2020 5:25 AM, Cameron Simpson wrote: >>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

[Python-Dev] Re: docs: I'd like new features to references their PEPs

2020-09-14 Thread Cameron Simpson
On 14Sep2020 18:17, Terry Reedy wrote: >On 9/14/2020 5:25 AM, Cameron Simpson wrote: >>On 14Sep2020 01:16, Ned Deily wrote: >>>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

[Python-Dev] Re: docs: I'd like new features to references their PEPs

2020-09-14 Thread Terry Reedy
On 9/14/2020 5:25 AM, Cameron Simpson wrote: 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

[Python-Dev] Re: docs: I'd like new features to references their PEPs

2020-09-14 Thread Guido van Rossum
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

[Python-Dev] Re: docs: I'd like new features to references their PEPs

2020-09-14 Thread Brett Cannon
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

[Python-Dev] Re: docs: I'd like new features to references their PEPs

2020-09-14 Thread Brandt Bucher
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::

[Python-Dev] Re: docs: I'd like new features to references their PEPs

2020-09-14 Thread Barry Warsaw
gt; "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

[Python-Dev] Re: docs: I'd like new features to references their PEPs

2020-09-14 Thread Cameron Simpson
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

[Python-Dev] Re: docs: I'd like new features to references their PEPs

2020-09-13 Thread Ned Deily
On Sep 14, 2020, at 01:07, Cameron Simpson wrote: > On 13Sep2020 20:51, Guido van Rossum wrote: >> On Sun, Sep 13, 2020 at 8:12 PM Cameron Simpson 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

[Python-Dev] Re: docs: I'd like new features to references their PEPs

2020-09-13 Thread Cameron Simpson
On 13Sep2020 20:51, Guido van Rossum wrote: >On Sun, Sep 13, 2020 at 8:12 PM Cameron Simpson 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

[Python-Dev] Re: docs: I'd like new features to references their PEPs

2020-09-13 Thread Guido van Rossum
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