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

[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 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, Terry,

There's a PR here: https://github.com/python/cpython/pull/22269
It's associated with BPO: https://bugs.python.org/issue41787

>I agree with one master issue.  I would prefer short blurb. "Add 
>rationale for __length_hint__ and link to PEP ###.

I'm not sure this warrants a blurb. Not yet, anyway.

This is a tiny PR so that we can agree on a style for mentioning the 
PEP. If we agree, I'm hoping to followup with a PR for each whatsnew, 
working backwards from 3.8, mentioning the relevant PEPs as I locate 
them. Unless you'd rather something more fine grained.

I guess also if we agree I should patch the doc guidelines about "New in 
version N" lines (and changed/deprecated too, where those are PEP 
driven).

Also, for discussion, is a separate feature in the same BPO advocating 
modifying "New in version V" to put a link on "version V" to reference 
an anchor for the whatsnew entry, or the more specific in-the-whatsnew 
anchors where they exist.

Cheers,
Cameron Simpson 
___
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/TEJPSJS64PWTDLHU43TQEUHD7FUQMBQX/
Code of Conduct: http://python.org/psf/codeofconduct/

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

[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 devguide has the details including for 
>>>the inline markup role :pep:.
>>>
>>>https://devguide.python.org/documenting/#rest-inline-markup
>
>I agree with one master issue.  I would prefer short blurb. "Add 
>rationale for __length_hint__ and link to PEP ###.
>
>bpo lists you as triager only, not committer.  If so, I will help 
>review and merge if review is requested on PR.

BPO 41787: https://bugs.python.org/issue41787

I'll make a PR for PEP424 and __length_hint__ so that we can nail down 
an agreed approach with a concrete example.

Cheers,
Cameron Simpson 
___
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/OJV64SMNQB3ZNGQXUPJYZLLKHVRMOVFH/
Code of Conduct: http://python.org/psf/codeofconduct/

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

[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 probably know, 
the devguide has the details including for the inline markup role :pep:.

https://devguide.python.org/documenting/#rest-inline-markup


I agree with one master issue.  I would prefer short blurb. "Add 
rationale for __length_hint__ and link to PEP ###.


bpo lists you as triager only, not committer.  If so, I will help review 
and merge if review is requested on PR.


--
Terry Jan Reedy
___
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/CXBEWAYSCAZCU7QABRBTKNVPDM3LELUM/
Code of Conduct: http://python.org/psf/codeofconduct/

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

[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 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?)*

___
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/3XA6YB65SVPM2EAPHE36CWTY5GR73JFF/
Code of Conduct: http://python.org/psf/codeofconduct/

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

[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 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-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/2R4JJSJTCLVLWWQ4FKMMTVJ3UE3DVC2T/
> Code of Conduct: http://python.org/psf/codeofconduct/
>
___
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/GSCSRLHAD5X2OMFNY3WDWQRMS4CJN6BW/
Code of Conduct: http://python.org/psf/codeofconduct/

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

[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:: XXX" directive for reuse and consistency.
___
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/2R4JJSJTCLVLWWQ4FKMMTVJ3UE3DVC2T/
Code of Conduct: http://python.org/psf/codeofconduct/

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

[Barry Warsaw]

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-requ...@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-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 
> Subject: [Python-Dev] docs: I'd like new features to references their
> PEPs
> To: Python-Dev 
> 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 
> 
> --
> 
> 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="6ee04305af3df322"
> Message: 2
> 
> --6ee04305af3df322
> 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.
> &g

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

[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 including for the inline markup role :pep:.
>
>https://devguide.python.org/documenting/#rest-inline-markup

Thanks Ned. - Cameron Simpson 
___
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/LWF2JWRRS6V7K4QCAORAFNGLH6A3JD67/
Code of Conduct: http://python.org/psf/codeofconduct/

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

[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 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 -- []
___
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/OEWCJIXELLPJXWIXJU6FNBG7UMOLOP6W/
Code of Conduct: http://python.org/psf/codeofconduct/

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

[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 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 
___
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/HO25HHHUBKETJYXWQ2Y7JTANALC6SRBS/
Code of Conduct: http://python.org/psf/codeofconduct/

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

[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 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?)*

___
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/ZGA7ZQDTYYTUTDGILCYDD45YXTSEFDWK/
Code of Conduct: http://python.org/psf/codeofconduct/