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

Thanks Ned. - Cameron Simpson 
___
Python-Dev mailing list -- [email protected]
To unsubscribe send an email to [email protected]
https://mail.python.org/mailman3/lists/python-dev.python.org/
Message archived at 
https://mail.python.org/archives/list/[email protected]/message/LWF2JWRRS6V7K4QCAORAFNGLH6A3JD67/
Code of Conduct: http://python.org/psf/codeofconduct/

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

2020-09-14 Thread 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: [email protected] 
> Sent: Monday, September 14, 2020 11:00 AM
> To: [email protected] 
> Subject: Python-Dev Digest, Vol 206, Issue 24
> 
> Send Python-Dev mailing list submissions to
> [email protected]
> 
> 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
> [email protected]
> 
> You can reach the person managing the list at
> [email protected]
> 
> 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: <[email protected]>
> 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.
> >
> > 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

[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:: XXX" directive for reuse and consistency.
___
Python-Dev mailing list -- [email protected]
To unsubscribe send an email to [email protected]
https://mail.python.org/mailman3/lists/python-dev.python.org/
Message archived at 
https://mail.python.org/archives/list/[email protected]/message/2R4JJSJTCLVLWWQ4FKMMTVJ3UE3DVC2T/
Code of Conduct: http://python.org/psf/codeofconduct/

[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 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 -- [email protected]
> To unsubscribe send an email to [email protected]
> https://mail.python.org/mailman3/lists/python-dev.python.org/
> Message archived at
> https://mail.python.org/archives/list/[email protected]/message/2R4JJSJTCLVLWWQ4FKMMTVJ3UE3DVC2T/
> Code of Conduct: http://python.org/psf/codeofconduct/
>
___
Python-Dev mailing list -- [email protected]
To unsubscribe send an email to [email protected]
https://mail.python.org/mailman3/lists/python-dev.python.org/
Message archived at 
https://mail.python.org/archives/list/[email protected]/message/GSCSRLHAD5X2OMFNY3WDWQRMS4CJN6BW/
Code of Conduct: http://python.org/psf/codeofconduct/

[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 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 -- [email protected]
To unsubscribe send an email to [email protected]
https://mail.python.org/mailman3/lists/python-dev.python.org/
Message archived at 
https://mail.python.org/archives/list/[email protected]/message/3XA6YB65SVPM2EAPHE36CWTY5GR73JFF/
Code of Conduct: http://python.org/psf/codeofconduct/

[Python-Dev] Python-checkins mailing list broken?

2020-09-14 Thread Jeremy Kloth 
It seems that python-checkins isn't receiving any new commits since
the 8th of September.  A quick check of the github page shows activity
since then, as do the buildbots.

Just a heads up.

-- 
Jeremy Kloth
___
Python-Dev mailing list -- [email protected]
To unsubscribe send an email to [email protected]
https://mail.python.org/mailman3/lists/python-dev.python.org/
Message archived at 
https://mail.python.org/archives/list/[email protected]/message/NLLZVN7GBRVN3UCK7AORNSUFWQCOJX67/
Code of Conduct: http://python.org/psf/codeofconduct/

[Python-Dev] Re: Python-checkins mailing list broken?

2020-09-14 Thread Guido van Rossum 
Maybe this is relevant?
https://discuss.python.org/t/webhook-mailer-sends-emails-without-subjects/1974/4

On Mon, Sep 14, 2020 at 12:48 PM Jeremy Kloth 
wrote:

> It seems that python-checkins isn't receiving any new commits since
> the 8th of September.  A quick check of the github page shows activity
> since then, as do the buildbots.
>
> Just a heads up.
>
> --
> Jeremy Kloth
> ___
> Python-Dev mailing list -- [email protected]
> To unsubscribe send an email to [email protected]
> https://mail.python.org/mailman3/lists/python-dev.python.org/
> Message archived at
> https://mail.python.org/archives/list/[email protected]/message/NLLZVN7GBRVN3UCK7AORNSUFWQCOJX67/
> Code of Conduct: http://python.org/psf/codeofconduct/
>


-- 
--Guido van Rossum (python.org/~guido)
*Pronouns: he/him **(why is my pronoun here?)*

___
Python-Dev mailing list -- [email protected]
To unsubscribe send an email to [email protected]
https://mail.python.org/mailman3/lists/python-dev.python.org/
Message archived at 
https://mail.python.org/archives/list/[email protected]/message/E2VH4W42QGEM2FIFWMRLWP7VQN6FJZR4/
Code of Conduct: http://python.org/psf/codeofconduct/

[Python-Dev] Re: Python-checkins mailing list broken?

2020-09-14 Thread Mariatta 
On Mon, Sep 14, 2020 at 12:49 PM Jeremy Kloth 
wrote:

> It seems that python-checkins isn't receiving any new commits since
> the 8th of September.  A quick check of the github page shows activity
> since then, as do the buildbots.
>
> Just a heads up.


Does anyone know whether the python-checkins list depends on
cpython-mailer webhook? When I look at the webhook deliveries (from
GitHub), it has been erroring out since September 8.

The webhook error message:
We couldn’t deliver this payload: timed out

I think one of the webhook maintainers should look into it. (I'm not the
maintainer)
___
Python-Dev mailing list -- [email protected]
To unsubscribe send an email to [email protected]
https://mail.python.org/mailman3/lists/python-dev.python.org/
Message archived at 
https://mail.python.org/archives/list/[email protected]/message/DYB4SXMEUO22TCQ3VPMNPXS42GDSSJD4/
Code of Conduct: http://python.org/psf/codeofconduct/

[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 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 -- [email protected]
To unsubscribe send an email to [email protected]
https://mail.python.org/mailman3/lists/python-dev.python.org/
Message archived at 
https://mail.python.org/archives/list/[email protected]/message/CXBEWAYSCAZCU7QABRBTKNVPDM3LELUM/
Code of Conduct: http://python.org/psf/codeofconduct/

[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 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 -- [email protected]
To unsubscribe send an email to [email protected]
https://mail.python.org/mailman3/lists/python-dev.python.org/
Message archived at 
https://mail.python.org/archives/list/[email protected]/message/OJV64SMNQB3ZNGQXUPJYZLLKHVRMOVFH/
Code of Conduct: http://python.org/psf/codeofconduct/