[Python-Dev] Re: Inline links in Misc/NEWS entries

[Kyle Stanley]

> the talk I gave last month at PyOhio (
https://www.pyohio.org/2019/presentations/137)

> Right now I have the slides up as a view-only share in my Google Drive (
bit.ly/bskinn-pyohio2019-intersphinx). Perhaps it would be useful to link
to them? Or, to host a PDF someplace more permanent, and link to that?

Thanks for the links, I'll definitely take a look through them for myself
to see if I can gain any additional information. I've been using Sphinx and
reST a decent amount recently, but I'm definitely not the most experienced.

Also, there's a PR open for providing netlify previews for CPython PRs:
https://github.com/python/cpython/pull/15288. From what I understand, we'll
be recommending for PR authors to use that to preview documentation
changes, particularly when any rich formatting is involved.

> - [ ] And a *link*/"reference" from the "extensive cross-references"
paragraph of https://www.sphinx-doc.org/en/master/ to the cross-referencing
docs

We currently link to the Sphinx docs in the dedicated section, "Additional
Markup Constructs":
https://devguide.python.org/documenting/#additional-markup-constructs. The
section in the PR was only meant to provide a very brief summary for using
Sphinx in NEWS entries. I included a link to the "Additional Markup
Constructs" section for readers looking for additional information.

It might be worthwhile to create a new subsection for links to external
resources and guides. If accepted, the best location in the devguide would
probably be 7.4.12 (assuming that no other sections are added in the
meantime). However, that proposal would have to be in it's own topic,
rather than in this one.


On Mon, Aug 19, 2019 at 12:33 PM Wes Turner  wrote:

> - [ ] A page or section in the Sphinx docs would be helpful for many, I
> think
>
> https://github.com/sphinx-doc/sphinx/tree/master/doc
>
> ``__
>
>
> .. index:: Implicit reference
> .. _implicit-reference:
>
> Implicit ref
> ---
>
> `implicit ref`_
>
> `anchor text `_
>
> `implicit-reference`_
>
> `implicit reference`_
>
> :func:`modname.funcname`
>
> :meth:`modname.Classname.methname`
>
> :class:`modname.Classname`
>
> And, FWIW:
>
> :cite:`cpython37`
>
> .. bibliography:: references.bib
>
> References.bib
> --
> .. code:: latex
>
> @techreport{cpython37,
> title="Python 3.7 Documentation",
> author="Python Software Foundation",
> year=1999,
> howpublished = "\url{https://docs.python.org/3.7/};,
> }
>
>
>
> - [ ] And/Or examples on the roles docs page
> https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#ref-role
>
> - [ ] And a *link*/"reference" from the "extensive cross-references"
> paragraph of https://www.sphinx-doc.org/en/master/ to the
> cross-referencing docs
>
> - [ ] And how to do parenthetical citations of / reference CPython with
> e.g. bibtex [with the `.. bibliography::` directive and :cite:`refkey` role
> from sphinxcontrib-bibtex]
>
> There are lots of great Sphinx primers; awesome-sphinxdoc could link to
> them to help everyone:
> https://github.com/yoloseem/awesome-sphinxdoc
>
> On Monday, August 19, 2019,  wrote:
>
>> Citing from the current (19 Aug 2019) version of this PR (
>> https://github.com/python/devguide/pull/525/files#diff-50cb76bbe8ae3fcd4170dc6e8d9d6b3fR225-R226
>> ):
>>
>> > Before using any Sphinx roles, ensure that a corresponding entry exists
>> within the documentation.
>>
>> At the risk of crass self-promotion, the talk I gave last month at PyOhio
>> (https://www.pyohio.org/2019/presentations/137) provides step-by-step
>> instructions for how to find the information needed to craft a working
>> Sphinx cross-reference, along with some of the tooling that's available.
>>
>> Right now I have the slides up as a view-only share in my Google Drive (
>> bit.ly/bskinn-pyohio2019-intersphinx). Perhaps it would be useful to
>> link to them? Or, to host a PDF someplace more permanent, and link to that?
>> ___
>> 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/IK5XP7CPZDF2FSFG55JRKXHEXNTOMUTB/
>>
> ___
> 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/SSMNWK7YF6WRT2NO4C2IQ6PGD2XVJOZT/
>
___
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 

[Python-Dev] Re: Inline links in Misc/NEWS entries

[Wes Turner]

- [ ] A page or section in the Sphinx docs would be helpful for many, I
think

https://github.com/sphinx-doc/sphinx/tree/master/doc

``__


.. index:: Implicit reference
.. _implicit-reference:

Implicit ref
---

`implicit ref`_

`anchor text `_

`implicit-reference`_

`implicit reference`_

:func:`modname.funcname`

:meth:`modname.Classname.methname`

:class:`modname.Classname`

And, FWIW:

:cite:`cpython37`

.. bibliography:: references.bib

References.bib
--
.. code:: latex

@techreport{cpython37,
title="Python 3.7 Documentation",
author="Python Software Foundation",
year=1999,
howpublished = "\url{https://docs.python.org/3.7/};,
}



- [ ] And/Or examples on the roles docs page
https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#ref-role

- [ ] And a *link*/"reference" from the "extensive cross-references"
paragraph of https://www.sphinx-doc.org/en/master/ to the cross-referencing
docs

- [ ] And how to do parenthetical citations of / reference CPython with
e.g. bibtex [with the `.. bibliography::` directive and :cite:`refkey` role
from sphinxcontrib-bibtex]

There are lots of great Sphinx primers; awesome-sphinxdoc could link to
them to help everyone:
https://github.com/yoloseem/awesome-sphinxdoc

On Monday, August 19, 2019,  wrote:

> Citing from the current (19 Aug 2019) version of this PR (
> https://github.com/python/devguide/pull/525/files#diff-
> 50cb76bbe8ae3fcd4170dc6e8d9d6b3fR225-R226):
>
> > Before using any Sphinx roles, ensure that a corresponding entry exists
> within the documentation.
>
> At the risk of crass self-promotion, the talk I gave last month at PyOhio (
> https://www.pyohio.org/2019/presentations/137) provides step-by-step
> instructions for how to find the information needed to craft a working
> Sphinx cross-reference, along with some of the tooling that's available.
>
> Right now I have the slides up as a view-only share in my Google Drive (
> bit.ly/bskinn-pyohio2019-intersphinx). Perhaps it would be useful to link
> to them? Or, to host a PDF someplace more permanent, and link to that?
> ___
> 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/IK5XP7CPZDF2FSFG55JRKXHEXNTOMUTB/
>
___
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/SSMNWK7YF6WRT2NO4C2IQ6PGD2XVJOZT/

[Python-Dev] Re: Inline links in Misc/NEWS entries

[brian . skinn]

Citing from the current (19 Aug 2019) version of this PR 
(https://github.com/python/devguide/pull/525/files#diff-50cb76bbe8ae3fcd4170dc6e8d9d6b3fR225-R226):

> Before using any Sphinx roles, ensure that a corresponding entry exists 
> within the documentation.

At the risk of crass self-promotion, the talk I gave last month at PyOhio 
(https://www.pyohio.org/2019/presentations/137) provides step-by-step 
instructions for how to find the information needed to craft a working Sphinx 
cross-reference, along with some of the tooling that's available.

Right now I have the slides up as a view-only share in my Google Drive 
(bit.ly/bskinn-pyohio2019-intersphinx). Perhaps it would be useful to link to 
them? Or, to host a PDF someplace more permanent, and link to that?
___
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/IK5XP7CPZDF2FSFG55JRKXHEXNTOMUTB/

[Python-Dev] Re: Inline links in Misc/NEWS entries

[Kyle Stanley]

Based on the feedback from the ML thread and Discuss topic, I created a new
PR on python/devguide which expands the "What's New and News Entries"
section of "committing.rst" to include Sphinx roles:
https://github.com/python/devguide/pull/525/files

I would greatly appreciate feedback from contributors and developers less
experienced with documentation to ensure that the section is easy to
understand for the intended target audience. Also, review from those who
are experienced with documentation and news entries is needed to ensure it
is as accurate as possible.

Thanks,
Kyle Stanley

On Mon, Aug 12, 2019 at 10:24 PM Kyle Stanley  wrote:

> Recently, on Discuss, I created a new topic:
> https://discuss.python.org/t/should-news-entries-contain-documentation-links/2127
>
> However, many may not have the time to read the full post or don’t
> regularly check the core workflow category on Discuss, so I'll provide a
> shortened version here.
>
> During my experience thus far reviewing PRs on GitHub, I've noticed a
> significant degree of inconsistency when it comes to the usage of inline
> links with reST and Sphinx in Misc/NEWS entries. Since many of my
> contributions have involved documentation changes, I've familiarized myself
> most of the syntax.
>
> Many of the features in markup languages provide visual modifications
> rather than functional ones. However, with the inline markup supported by
> reST and processing from Sphinx, there's a functional improvement as well.
> For example, the usage of :func:\`\` (escaped for mailman)
> provides a link to the relevant docs for the function.
>
> In the context of news entries, this allows readers to click on a
> function, method, class, etc for more information. This can be useful if
> it's something they're not familiar with, or when the changes affected the
> docs. For those who are familiar with the structure of docs.python.org,
> the cross link to the docs may not seem at all necessary.
>
> However, for readers that are either newer or not familiar with the
> structure, they might be led astray into 2.7 docs or an entirely wrong
> page. This happens especially frequently when using external search engines.
>
> I'm not at all suggesting that every PR author should be required to use
> it or know all of the reST constructs. However, I would like for everyone
> to be aware of the potential usefulness of including inline links in news
> entries, and mention it in the devguide.
>
> Also, I would like to understand why some developers dislike including it,
> even when the reST syntax is provided. The majority of authors so far would
> add my suggestion to their PR, but there have been some that don't want
> anything besides plaintext in their news entry.
>
> Personally, I think it provides further inclusiveness to readers of all
> levels of experience and QoL at a very minimal cost.
> ___
> 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/HTAFGTQIZJQUCU6QCVF3KFD3VFGFOBWV/
>
___
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/2VI4OZI7YTFUXW4LUETY3QYZ3TU6BU7J/

[Python-Dev] Re: Inline links in Misc/NEWS entries

[Kyle Stanley]

> a) this seems to be "well-defined", and imho, suitable as "easy", etc..

Part of this could potentially be suitable as an "easy" issue, but I'm not
certain that it would make for a good first PR, since it is involving a
fairly important and widely used section of the devguide. Many newcomers
may not be familiar with what would be considered "appropriate usage" of
the Sphinx roles in news entries. When I think of issues that would be good
first PRs involving documentation, I generally think of grammar/spelling
improvements or perhaps more objective fixes. This section might be a
little bit too subjective though.

> b) isn't this something we want new people to be more aware of (as you
> said, you have been working with this for a year)

I think you might be confusing me with someone else, as I've only been
contributing to Python since June of this year. I've built up some amount
of experience from PRs I've submitted as well as PR reviews, but I would
still consider myself to be a more recent contributor. If I come across as
having more experience though, that's certainly a good thing. (:

> c) it is an area (Documentation) I have clearly 'missed' as I focused on
> 'other things', and, with myself and many projects I have worked on over
> the years - Documentation seems to come in last. Getting new (and
> newish, as myself) working here only makes us better suited for review
> in the future.

I definitely agree that we should try to come up with ways to improve the
interaction with the documentation (particularly with the devguide). A
great way to do that can be cleaning up existing sections, but for reasons
previously stated, I'm not certain that this issue is particularly well
suited for that. It's "well-defined" from feedback in the mailing list
discussion, but I think it would benefit from being written by someone with
some experience in news entries, reST and Sphinx markup, and documentation
in general.

However, a great way that anyone could help out would be through providing
feedback on the PR once it's open. Providing feedback on PRs is great way
to improve experience in an area, and also helps to deal with a major
bottleneck for Python development in general. We have far more people
submitting PRs than reviewers.

Once I open the PR for it in the devguide, I'll be sure to send a message
in this topic which includes a link to it. It would greatly benefit from
review from those who are less familiar with documentation. That will help
to ensure the section is easy to understand for the intended target
audience. Of course, it would also benefit from those are are experienced
as well, to ensure it is as accurate as possible.

Thanks,
Kyle Stanley

On Fri, Aug 16, 2019 at 4:48 AM Michael  wrote:

> On 16/08/2019 05:31, Kyle Stanley wrote:
> > Yeah definitely, it was my intention to mention this in the devguide,
> > particularly with adding an example of the Sphinx roles being used and
> > explaining appropriate usage. I hadn't thought of linking to the list of
> > roles (https://devguide.python.org/documenting/#id4), but that's
> definitely
> > a good idea to include. I was just waiting for everyone to get a chance
> to
> > provide feedback on the topic before expanding the devguide.
> >
> > After the devguide is updated, I was also planning on adding the markup
> to
> > 3.8's Misc/NEWS entries (in the appropriate branch, as Ned recommended),
> > and then work on the 3.9. I'll probably split it into several smaller PRs
> > so it's easier to review.
>
> There has been "a lot" of discussion re: things for new contributors to
> do and learn.
>
> a) this seems to be "well-defined", and imho, suitable as "easy", etc..
> b) isn't this something we want new people to be more aware of (as you
> said, you have been working with this for a year)
> c) it is an area (Documentation) I have clearly 'missed' as I focused on
> 'other things', and, with myself and many projects I have worked on over
> the years - Documentation seems to come in last. Getting new (and
> newish, as myself) working here only makes us better suited for review
> in the future.
>
> So, I guess this is an area where you could "mentor", perhaps create
> "issues" that specify the "paragraphs", or whatever you think are
> appropriate 'chunks' to make review sensible (if not also easier).
>
> Michael
>
>
>
___
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/ROXFQX7ZDXFH5YRNGYZU3KCF7GR5QQLL/

[Python-Dev] Re: Inline links in Misc/NEWS entries

[Michael]

On 16/08/2019 05:31, Kyle Stanley wrote:
> Yeah definitely, it was my intention to mention this in the devguide,
> particularly with adding an example of the Sphinx roles being used and
> explaining appropriate usage. I hadn't thought of linking to the list of
> roles (https://devguide.python.org/documenting/#id4), but that's definitely
> a good idea to include. I was just waiting for everyone to get a chance to
> provide feedback on the topic before expanding the devguide.
>
> After the devguide is updated, I was also planning on adding the markup to
> 3.8's Misc/NEWS entries (in the appropriate branch, as Ned recommended),
> and then work on the 3.9. I'll probably split it into several smaller PRs
> so it's easier to review.

There has been "a lot" of discussion re: things for new contributors to
do and learn.

a) this seems to be "well-defined", and imho, suitable as "easy", etc..
b) isn't this something we want new people to be more aware of (as you
said, you have been working with this for a year)
c) it is an area (Documentation) I have clearly 'missed' as I focused on
'other things', and, with myself and many projects I have worked on over
the years - Documentation seems to come in last. Getting new (and
newish, as myself) working here only makes us better suited for review
in the future.

So, I guess this is an area where you could "mentor", perhaps create
"issues" that specify the "paragraphs", or whatever you think are
appropriate 'chunks' to make review sensible (if not also easier).

Michael




signature.asc
Description: OpenPGP digital signature
___
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/T5YQW2I624S7UU63AXNBNGOH7ASF6OWC/

[Python-Dev] Re: Inline links in Misc/NEWS entries

[Kyle Stanley]

> I suggest slightly expanding the part about NEWS formatting in the dev
guide, and specifically have the example include appropriate uses of roles,
and a link to the list of available roles.

Yeah definitely, it was my intention to mention this in the devguide,
particularly with adding an example of the Sphinx roles being used and
explaining appropriate usage. I hadn't thought of linking to the list of
roles (https://devguide.python.org/documenting/#id4), but that's definitely
a good idea to include. I was just waiting for everyone to get a chance to
provide feedback on the topic before expanding the devguide.

After the devguide is updated, I was also planning on adding the markup to
3.8's Misc/NEWS entries (in the appropriate branch, as Ned recommended),
and then work on the 3.9. I'll probably split it into several smaller PRs
so it's easier to review.

On Thu, Aug 15, 2019 at 3:10 AM Tal Einat  wrote:

> I suggest slightly expanding the part about NEWS formatting in the dev
> guide, and specifically have the example include appropriate uses of roles,
> and a link to the list of available roles.
>
> https://devguide.python.org/committing/#what-s-new-and-news-entries
>
> On Thu, Aug 15, 2019 at 3:39 AM Kyle Stanley  wrote:
>
>> > Also, for IDLE, news entries to idlelib/NEWS.txt
>> > where markup, as opposed to unicode, is noise.
>>
>> Interesting, I actually wasn't aware of the distinction for idlelib/NEWS.
>> I can imagine that Sphinx constructs such as :func:, :meth:, and :class:
>> would not be nearly as useful there. However, I can imagine reST being
>> occasionally useful.
>>
>> Based on a recent feature that was added to the IDLE, I could imagine
>> explicit inline reST links being somewhat useful for something like this:
>>
>> Add support for displaying line numbers. See `IDLE Options menu <
>> https://docs.python.org/3/library/idle.html#options-menu-shell-and-editor
>> >`_.
>>
>> The inline link would appear to readers as "IDLE Options menu" and allow
>> them to click on it to navigate to the corresponding documentation for more
>> information on the feature.
>>
>> > Bottom line: I would rather a knowledgeable editor prettify the blurbs
>> > in a consistent manner after I am done with them.  To me, this is a
>> > place where specializations pays.
>>
>> I completely agree. I was mainly addressing situations where PR authors
>> were rejecting or disregarding suggestions to add the markup in the news
>> entry from those who are knowledgeable of the Sphinx constructs/roles. It
>> wouldn't be reasonable to expect all PR authors to be able to properly
>> utilize every supported markup feature.
>>
>> This is a rare occurrence, but I've had it happen a couple of times
>> recently. Based on the responses so far, it likely occurred due to some
>> developers not being aware that Misc/NEWS supported Sphinx roles and some
>> of the basic features of reST. That's completely understandable if it's a
>> newer feature.
>>
>> Hopefully this discussion and any potential updates to the devguide will
>> improve awareness of the feature, and provide instructions on when it's
>> appropriate to utilize.
>>
>> Thanks,
>> Kyle Stanley
>>
>> On Wed, Aug 14, 2019 at 3:31 AM Terry Reedy  wrote:
>>
>>> On 8/13/2019 6:31 PM, Kyle Stanley wrote:
>>>
>>> > The primary purpose of me creating this topic was because there seems
>>> to
>>> > be some sentiment that it's perfectly fine to exclusively use
>>> plaintext
>>> > in the news entries. Especially in cases where authors have rejected
>>> > suggestions to adding the Sphinx markup in their PRs. There seems to
>>> be
>>> > some sentiment that it's perfectly fine to exclusively use plaintext
>>> in
>>> > every news entry. Personally, I think it's a bit more nuanced, and
>>> that
>>> > the links can sometimes be very helpful for readers.
>>>
>>> Beyond what Ned said, (news markup is relatively new), people may be
>>> uncertain what is allowed and when appropriate.  Also, there is some
>>> situation for me where markup seems to be a nuisance and looks like it
>>> is introducing an error.  So I have changed unicode quotes and removed
>>> some rst markup.  Also, for IDLE, news entries to idlelib/NEWS.txt.
>>> where markup, as opposed to unicode, is noise.
>>>
>>> Bottom line: I would rather a knowledgeable editor prettify the blurbs
>>> in a consistent manner after I am done with them.  To me, this is a
>>> place where specializations pays.
>>>
>>> --
>>> 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/53QDMBQHW2S6F7JI4YSGAYYKJOVOIFQF/
>>>
>> ___
>> Python-Dev mailing list -- python-dev@python.org
>> To unsubscribe send an email to 

[Python-Dev] Re: Inline links in Misc/NEWS entries

[Tal Einat]

I suggest slightly expanding the part about NEWS formatting in the dev
guide, and specifically have the example include appropriate uses of roles,
and a link to the list of available roles.

https://devguide.python.org/committing/#what-s-new-and-news-entries

On Thu, Aug 15, 2019 at 3:39 AM Kyle Stanley  wrote:

> > Also, for IDLE, news entries to idlelib/NEWS.txt
> > where markup, as opposed to unicode, is noise.
>
> Interesting, I actually wasn't aware of the distinction for idlelib/NEWS.
> I can imagine that Sphinx constructs such as :func:, :meth:, and :class:
> would not be nearly as useful there. However, I can imagine reST being
> occasionally useful.
>
> Based on a recent feature that was added to the IDLE, I could imagine
> explicit inline reST links being somewhat useful for something like this:
>
> Add support for displaying line numbers. See `IDLE Options menu <
> https://docs.python.org/3/library/idle.html#options-menu-shell-and-editor
> >`_.
>
> The inline link would appear to readers as "IDLE Options menu" and allow
> them to click on it to navigate to the corresponding documentation for more
> information on the feature.
>
> > Bottom line: I would rather a knowledgeable editor prettify the blurbs
> > in a consistent manner after I am done with them.  To me, this is a
> > place where specializations pays.
>
> I completely agree. I was mainly addressing situations where PR authors
> were rejecting or disregarding suggestions to add the markup in the news
> entry from those who are knowledgeable of the Sphinx constructs/roles. It
> wouldn't be reasonable to expect all PR authors to be able to properly
> utilize every supported markup feature.
>
> This is a rare occurrence, but I've had it happen a couple of times
> recently. Based on the responses so far, it likely occurred due to some
> developers not being aware that Misc/NEWS supported Sphinx roles and some
> of the basic features of reST. That's completely understandable if it's a
> newer feature.
>
> Hopefully this discussion and any potential updates to the devguide will
> improve awareness of the feature, and provide instructions on when it's
> appropriate to utilize.
>
> Thanks,
> Kyle Stanley
>
> On Wed, Aug 14, 2019 at 3:31 AM Terry Reedy  wrote:
>
>> On 8/13/2019 6:31 PM, Kyle Stanley wrote:
>>
>> > The primary purpose of me creating this topic was because there seems
>> to
>> > be some sentiment that it's perfectly fine to exclusively use plaintext
>> > in the news entries. Especially in cases where authors have rejected
>> > suggestions to adding the Sphinx markup in their PRs. There seems to be
>> > some sentiment that it's perfectly fine to exclusively use plaintext in
>> > every news entry. Personally, I think it's a bit more nuanced, and that
>> > the links can sometimes be very helpful for readers.
>>
>> Beyond what Ned said, (news markup is relatively new), people may be
>> uncertain what is allowed and when appropriate.  Also, there is some
>> situation for me where markup seems to be a nuisance and looks like it
>> is introducing an error.  So I have changed unicode quotes and removed
>> some rst markup.  Also, for IDLE, news entries to idlelib/NEWS.txt.
>> where markup, as opposed to unicode, is noise.
>>
>> Bottom line: I would rather a knowledgeable editor prettify the blurbs
>> in a consistent manner after I am done with them.  To me, this is a
>> place where specializations pays.
>>
>> --
>> 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/53QDMBQHW2S6F7JI4YSGAYYKJOVOIFQF/
>>
> ___
> 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/K5TXWQ7ARKDV73MNEIED35PZDAL6T2L2/
>
___
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/DZSQL4MYVHFQENLGQK2QLNNZKSYF33CJ/

[Python-Dev] Re: Inline links in Misc/NEWS entries

[Kyle Stanley]

> Also, for IDLE, news entries to idlelib/NEWS.txt
> where markup, as opposed to unicode, is noise.

Interesting, I actually wasn't aware of the distinction for idlelib/NEWS. I
can imagine that Sphinx constructs such as :func:, :meth:, and :class:
would not be nearly as useful there. However, I can imagine reST being
occasionally useful.

Based on a recent feature that was added to the IDLE, I could imagine
explicit inline reST links being somewhat useful for something like this:

Add support for displaying line numbers. See `IDLE Options menu <
https://docs.python.org/3/library/idle.html#options-menu-shell-and-editor
>`_.

The inline link would appear to readers as "IDLE Options menu" and allow
them to click on it to navigate to the corresponding documentation for more
information on the feature.

> Bottom line: I would rather a knowledgeable editor prettify the blurbs
> in a consistent manner after I am done with them.  To me, this is a
> place where specializations pays.

I completely agree. I was mainly addressing situations where PR authors
were rejecting or disregarding suggestions to add the markup in the news
entry from those who are knowledgeable of the Sphinx constructs/roles. It
wouldn't be reasonable to expect all PR authors to be able to properly
utilize every supported markup feature.

This is a rare occurrence, but I've had it happen a couple of times
recently. Based on the responses so far, it likely occurred due to some
developers not being aware that Misc/NEWS supported Sphinx roles and some
of the basic features of reST. That's completely understandable if it's a
newer feature.

Hopefully this discussion and any potential updates to the devguide will
improve awareness of the feature, and provide instructions on when it's
appropriate to utilize.

Thanks,
Kyle Stanley

On Wed, Aug 14, 2019 at 3:31 AM Terry Reedy  wrote:

> On 8/13/2019 6:31 PM, Kyle Stanley wrote:
>
> > The primary purpose of me creating this topic was because there seems to
> > be some sentiment that it's perfectly fine to exclusively use plaintext
> > in the news entries. Especially in cases where authors have rejected
> > suggestions to adding the Sphinx markup in their PRs. There seems to be
> > some sentiment that it's perfectly fine to exclusively use plaintext in
> > every news entry. Personally, I think it's a bit more nuanced, and that
> > the links can sometimes be very helpful for readers.
>
> Beyond what Ned said, (news markup is relatively new), people may be
> uncertain what is allowed and when appropriate.  Also, there is some
> situation for me where markup seems to be a nuisance and looks like it
> is introducing an error.  So I have changed unicode quotes and removed
> some rst markup.  Also, for IDLE, news entries to idlelib/NEWS.txt.
> where markup, as opposed to unicode, is noise.
>
> Bottom line: I would rather a knowledgeable editor prettify the blurbs
> in a consistent manner after I am done with them.  To me, this is a
> place where specializations pays.
>
> --
> 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/53QDMBQHW2S6F7JI4YSGAYYKJOVOIFQF/
>
___
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/K5TXWQ7ARKDV73MNEIED35PZDAL6T2L2/

[Python-Dev] Re: Inline links in Misc/NEWS entries

[Terry Reedy]

On 8/13/2019 6:31 PM, Kyle Stanley wrote:

The primary purpose of me creating this topic was because there seems to 
be some sentiment that it's perfectly fine to exclusively use plaintext 
in the news entries. Especially in cases where authors have rejected 
suggestions to adding the Sphinx markup in their PRs. There seems to be 
some sentiment that it's perfectly fine to exclusively use plaintext in 
every news entry. Personally, I think it's a bit more nuanced, and that 
the links can sometimes be very helpful for readers.


Beyond what Ned said, (news markup is relatively new), people may be 
uncertain what is allowed and when appropriate.  Also, there is some 
situation for me where markup seems to be a nuisance and looks like it 
is introducing an error.  So I have changed unicode quotes and removed 
some rst markup.  Also, for IDLE, news entries to idlelib/NEWS.txt. 
where markup, as opposed to unicode, is noise.


Bottom line: I would rather a knowledgeable editor prettify the blurbs 
in a consistent manner after I am done with them.  To me, this is a 
place where specializations pays.


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

[Python-Dev] Re: Inline links in Misc/NEWS entries

[Kyle Stanley]

> Could a bot be written to suggest upgraded markup for Misc/NEWS entries
as a PR?

Potentially, but to some degree, the decision of whether or not to use the
Sphinx markup should be determined on a case by case basis, rather than
indiscriminately applying the markup to every possible candidate.
Generally, I've tried to only recommend to usage of the markup when the
inline link would provide a potential benefit to the readers. Adding the
markup to every possible candidate would result in an excessive number of
irrelevant links and potentially lead to more dead links to clean up in the
future as well.

Thanks,
Kyle Stanley

On Tue, Aug 13, 2019 at 11:30 PM Wes Turner  wrote:

> Could a bot be written to suggest upgraded markup for Misc/NEWS entries as
> a PR?
>
> Most e.g. class, method, and function references probably need ReST markup
> AND a more specific fully-qualified reference?
>
> Can class, method, and function lookups be done with the existing Sphinx
> API index?
>
> On Tuesday, August 13, 2019, Ned Deily  wrote:
>
>> On Aug 13, 2019, at 15:31, Kyle Stanley  wrote:
>> > > In general, using many Python-specific Sphinx markup entities is
>> fine: browsing though the consolidated blurb files for previous releases
>> (and the resultant changelog html) shows uses of entities like :func: and
>> :class:.
>> >
>> > Since it's okay to use Python-specific Sphinx, should we encourage the
>> usage of it when appropriate, such as when the links could provide helpful
>> information to users?
>> >
>> > The primary purpose of me creating this topic was because there seems
>> to be some sentiment that it's perfectly fine to exclusively use plaintext
>> in the news entries. Especially in cases where authors have rejected
>> suggestions to adding the Sphinx markup in their PRs. There seems to be
>> some sentiment that it's perfectly fine to exclusively use plaintext in
>> every news entry. Personally, I think it's a bit more nuanced, and that the
>> links can sometimes be very helpful for readers.
>>
>> The ability to effectively use Python-specific Sphinx features in NEWS
>> entries is a relatively new feature so I think that is the primary reason
>> it is not encouraged more: many people don't realize you can now do this.
>> Back in the day, NEWS files were just treated as plaintext, not reST.  This
>> is still the case for Python 2.7 NEWS entries as the 2.7 docset was never
>> modified to produce an HTML changelog as the Python 3.x docsets do.  (Of
>> course, that will soon be a non-issue when 2.7 reaches end-of-life status
>> in 2020.)
>>
>> > Also, a related question: would it be helpful for contributors to look
>> through news entries for the latest stable and beta releases, and add
>> inline links where they could be useful for readers?
>>
>> We haven't done a lot of that in the past but I don't see a reason not
>> to, especially since it is easy on most systems to generate the changelog
>> by building the html docs in the source tree:
>>
>> https://devguide.python.org/documenting/#using-make-make-bat
>>
>> and then opening the resultant docs in your browser as a file (the html
>> docs are self-contained with regard to static files and do not need a
>> webserver).
>>
>> But other people may have other opinions on the matter.  We could
>> undoubtedly spend a lot of time tidying up old NEWS entries and, at some
>> point, that time might be better spent on other things, like helping with
>> the "What's New" documents for upcoming releases or just fixing bugs.  But
>> I think there could be a lot of benefit for a moderate bit of touching up.
>>
>> One important note: to avoid confusion, only edit the blurb NEWS rst
>> files in the branch for that release, i.e. edit Misc/NEWS.d/3.8.0b1.rst in
>> the 3.8 branch, not in the master branch.
>>
>> --
>>   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/WQNYODDNTH6MFPBNJZZJR6AFFTD5CYBG/
>>
>
___
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/4UIY6UDE6V2TEKN2CY6EXJG5MITXIQFJ/

[Python-Dev] Re: Inline links in Misc/NEWS entries

[Kyle Stanley]

> The ability to effectively use Python-specific Sphinx features in NEWS
entries is a relatively new feature

Ah, I think that would likely explain some of the inconsistent responses
then. I think it would be worthwhile to add an example of using Sphinx and
a brief explanation of when it can be useful in news entries. This would
likely help improve awareness of the feature.

> But other people may have other opinions on the matter.  We could
undoubtedly spend a lot of time tidying up old NEWS entries
> and, at some point, that time might be better spent on other things, like
helping with the "What's New" documents for upcoming
> releases or just fixing bugs.  But I think there could be a lot of
benefit for a moderate bit of touching up.

I would definitely agree that at some point, it could end up being a bit
overkill (especially for further back versions). However, with regards to
prioritizing different projects, such as tidying news entries vs fixing
bugs, I think a large part of that comes down to each developer's personal
priorities. Also, from my experience, PRs which involve tidying up
documentation have a tendency to be a bit easier to review, so in general
they would end up being less time consuming anyways.

Also, thanks for the tips! I'll definitely look into helping with this.

Thanks,
Kyle Stanley

On Tue, Aug 13, 2019 at 7:30 PM Ned Deily  wrote:

> On Aug 13, 2019, at 15:31, Kyle Stanley  wrote:
> > > In general, using many Python-specific Sphinx markup entities is fine:
> browsing though the consolidated blurb files for previous releases (and the
> resultant changelog html) shows uses of entities like :func: and :class:.
> >
> > Since it's okay to use Python-specific Sphinx, should we encourage the
> usage of it when appropriate, such as when the links could provide helpful
> information to users?
> >
> > The primary purpose of me creating this topic was because there seems to
> be some sentiment that it's perfectly fine to exclusively use plaintext in
> the news entries. Especially in cases where authors have rejected
> suggestions to adding the Sphinx markup in their PRs. There seems to be
> some sentiment that it's perfectly fine to exclusively use plaintext in
> every news entry. Personally, I think it's a bit more nuanced, and that the
> links can sometimes be very helpful for readers.
>
> The ability to effectively use Python-specific Sphinx features in NEWS
> entries is a relatively new feature so I think that is the primary reason
> it is not encouraged more: many people don't realize you can now do this.
> Back in the day, NEWS files were just treated as plaintext, not reST.  This
> is still the case for Python 2.7 NEWS entries as the 2.7 docset was never
> modified to produce an HTML changelog as the Python 3.x docsets do.  (Of
> course, that will soon be a non-issue when 2.7 reaches end-of-life status
> in 2020.)
>
> > Also, a related question: would it be helpful for contributors to look
> through news entries for the latest stable and beta releases, and add
> inline links where they could be useful for readers?
>
> We haven't done a lot of that in the past but I don't see a reason not to,
> especially since it is easy on most systems to generate the changelog by
> building the html docs in the source tree:
>
> https://devguide.python.org/documenting/#using-make-make-bat
>
> and then opening the resultant docs in your browser as a file (the html
> docs are self-contained with regard to static files and do not need a
> webserver).
>
> But other people may have other opinions on the matter.  We could
> undoubtedly spend a lot of time tidying up old NEWS entries and, at some
> point, that time might be better spent on other things, like helping with
> the "What's New" documents for upcoming releases or just fixing bugs.  But
> I think there could be a lot of benefit for a moderate bit of touching up.
>
> One important note: to avoid confusion, only edit the blurb NEWS rst files
> in the branch for that release, i.e. edit Misc/NEWS.d/3.8.0b1.rst in the
> 3.8 branch, not in the master branch.
>
> --
>   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/SSNKSLSCN5GQ5Z27235VVXA5UBFTU3YW/

[Python-Dev] Re: Inline links in Misc/NEWS entries

[Wes Turner]

Could a bot be written to suggest upgraded markup for Misc/NEWS entries as
a PR?

Most e.g. class, method, and function references probably need ReST markup
AND a more specific fully-qualified reference?

Can class, method, and function lookups be done with the existing Sphinx
API index?

On Tuesday, August 13, 2019, Ned Deily  wrote:

> On Aug 13, 2019, at 15:31, Kyle Stanley  wrote:
> > > In general, using many Python-specific Sphinx markup entities is fine:
> browsing though the consolidated blurb files for previous releases (and the
> resultant changelog html) shows uses of entities like :func: and :class:.
> >
> > Since it's okay to use Python-specific Sphinx, should we encourage the
> usage of it when appropriate, such as when the links could provide helpful
> information to users?
> >
> > The primary purpose of me creating this topic was because there seems to
> be some sentiment that it's perfectly fine to exclusively use plaintext in
> the news entries. Especially in cases where authors have rejected
> suggestions to adding the Sphinx markup in their PRs. There seems to be
> some sentiment that it's perfectly fine to exclusively use plaintext in
> every news entry. Personally, I think it's a bit more nuanced, and that the
> links can sometimes be very helpful for readers.
>
> The ability to effectively use Python-specific Sphinx features in NEWS
> entries is a relatively new feature so I think that is the primary reason
> it is not encouraged more: many people don't realize you can now do this.
> Back in the day, NEWS files were just treated as plaintext, not reST.  This
> is still the case for Python 2.7 NEWS entries as the 2.7 docset was never
> modified to produce an HTML changelog as the Python 3.x docsets do.  (Of
> course, that will soon be a non-issue when 2.7 reaches end-of-life status
> in 2020.)
>
> > Also, a related question: would it be helpful for contributors to look
> through news entries for the latest stable and beta releases, and add
> inline links where they could be useful for readers?
>
> We haven't done a lot of that in the past but I don't see a reason not to,
> especially since it is easy on most systems to generate the changelog by
> building the html docs in the source tree:
>
> https://devguide.python.org/documenting/#using-make-make-bat
>
> and then opening the resultant docs in your browser as a file (the html
> docs are self-contained with regard to static files and do not need a
> webserver).
>
> But other people may have other opinions on the matter.  We could
> undoubtedly spend a lot of time tidying up old NEWS entries and, at some
> point, that time might be better spent on other things, like helping with
> the "What's New" documents for upcoming releases or just fixing bugs.  But
> I think there could be a lot of benefit for a moderate bit of touching up.
>
> One important note: to avoid confusion, only edit the blurb NEWS rst files
> in the branch for that release, i.e. edit Misc/NEWS.d/3.8.0b1.rst in the
> 3.8 branch, not in the master branch.
>
> --
>   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/WQNYODDNTH6MFPBNJZZJR6AFFTD5CYBG/
>
___
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/QYXQ5UD34L2AQTQSUHJSEOYEBP4Q3HEB/

[Python-Dev] Re: Inline links in Misc/NEWS entries

[Ned Deily]

On Aug 13, 2019, at 15:31, Kyle Stanley  wrote:
> > In general, using many Python-specific Sphinx markup entities is fine: 
> > browsing though the consolidated blurb files for previous releases (and the 
> > resultant changelog html) shows uses of entities like :func: and :class:.
> 
> Since it's okay to use Python-specific Sphinx, should we encourage the usage 
> of it when appropriate, such as when the links could provide helpful 
> information to users? 
> 
> The primary purpose of me creating this topic was because there seems to be 
> some sentiment that it's perfectly fine to exclusively use plaintext in the 
> news entries. Especially in cases where authors have rejected suggestions to 
> adding the Sphinx markup in their PRs. There seems to be some sentiment that 
> it's perfectly fine to exclusively use plaintext in every news entry. 
> Personally, I think it's a bit more nuanced, and that the links can sometimes 
> be very helpful for readers.

The ability to effectively use Python-specific Sphinx features in NEWS entries 
is a relatively new feature so I think that is the primary reason it is not 
encouraged more: many people don't realize you can now do this.  Back in the 
day, NEWS files were just treated as plaintext, not reST.  This is still the 
case for Python 2.7 NEWS entries as the 2.7 docset was never modified to 
produce an HTML changelog as the Python 3.x docsets do.  (Of course, that will 
soon be a non-issue when 2.7 reaches end-of-life status in 2020.)

> Also, a related question: would it be helpful for contributors to look 
> through news entries for the latest stable and beta releases, and add inline 
> links where they could be useful for readers?

We haven't done a lot of that in the past but I don't see a reason not to, 
especially since it is easy on most systems to generate the changelog by 
building the html docs in the source tree:

https://devguide.python.org/documenting/#using-make-make-bat

and then opening the resultant docs in your browser as a file (the html docs 
are self-contained with regard to static files and do not need a webserver).

But other people may have other opinions on the matter.  We could undoubtedly 
spend a lot of time tidying up old NEWS entries and, at some point, that time 
might be better spent on other things, like helping with the "What's New" 
documents for upcoming releases or just fixing bugs.  But I think there could 
be a lot of benefit for a moderate bit of touching up.

One important note: to avoid confusion, only edit the blurb NEWS rst files in 
the branch for that release, i.e. edit Misc/NEWS.d/3.8.0b1.rst in the 3.8 
branch, not in the master branch.

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

[Python-Dev] Re: Inline links in Misc/NEWS entries

[Kyle Stanley]

> There seems to be some sentiment that it's perfectly fine to exclusively
use plaintext in every news entry.

Oops, that third sentence was a typo, I didn't intend to repeat myself
there.

On Tue, Aug 13, 2019 at 6:31 PM Kyle Stanley  wrote:

> > Note that there is an open devguide issue that requests improvements in
> the description of news entry processing
>
> Good to know, I'll look further into this issue and see if I can help with
> it.
>
> > In general, using many Python-specific Sphinx markup entities is fine:
> browsing though the consolidated blurb files for previous releases (and the
> resultant changelog html) shows uses of entities like :func: and :class:.
>
> Since it's okay to use Python-specific Sphinx, should we encourage the
> usage of it when appropriate, such as when the links could provide helpful
> information to users?
>
> The primary purpose of me creating this topic was because there seems to
> be some sentiment that it's perfectly fine to exclusively use plaintext in
> the news entries. Especially in cases where authors have rejected
> suggestions to adding the Sphinx markup in their PRs. There seems to be
> some sentiment that it's perfectly fine to exclusively use plaintext in
> every news entry. Personally, I think it's a bit more nuanced, and that the
> links can sometimes be very helpful for readers.
>
> > Readers interested in more detail can click on the link to the bpo issue
> for the full discussion and links to PRs and merges.
>
> Similarly to clicking on the bpo issue, users being able to also click on
> the link for functions and classes for more details also allow the news
> entry to be more succinct. Especially for changes involving complex
> modules, such as asyncio. But even for more simple changes, it shows newer
> readers where they can find more information on the more commonly used
> functions.
>
> Also, a related question: would it be helpful for contributors to look
> through news entries for the latest stable and beta releases, and add
> inline links where they could be useful for readers?
>
> I would be more than happy to help with this. A large part of the reason
> why I started contributing is because I've always been very pleased with
> the quality of Python's documentation and helpfulness towards newer users.
> It was my first programming language 5+ years ago. My primary goals are to
> further improve the documentation and other resources for newer users of
> the language.
>
> Thanks,
> Kyle Stanley
>
>
> On Tue, Aug 13, 2019 at 3:58 AM Ned Deily  wrote:
>
>> On Aug 13, 2019, at 00:20, Kyle Stanley  wrote:
>> > On Tue, Aug 13, 2019 at 2:41 AM Mariatta 
>> wrote:
>> > > I would like to understand why some developers dislike including it,
>> even when the reST syntax is provided.
>> >
>> > This has something to do with the use of blurb/blurb-it. Both tools
>> specifically say "single paragraph with simple ReST markup".
>> >
>> > Further reading blurb's source code, it says the format of the news
>> blurb should be as follows:
>> >   * The BODY section should be a single paragraph of English text
>> > in ReST format.  It should not use the following ReST markup
>> > features:
>> >   * section headers
>> >   * comments
>> >   * directives, citations, or footnotes
>> >   * Any features that require significant line breaks,
>> > like lists, definition lists, quoted paragraphs, line blocks,
>> > literal code blocks, and tables.
>>
>> Note that there is an open devguide issue that requests improvements in
>> the description of news entry processing:
>> https://github.com/python/devguide/issues/358
>>
>> Release managers are responsible for reviewing and editing, as necessary,
>> the changelog files that are produced in the docset for each release from
>> the individual blurb news items.  In general, using many Python-specific
>> Sphinx markup entities is fine: browsing though the consolidated blurb
>> files for previous releases (and the resultant changelog html) shows uses
>> of entities like :func: and :class:.  See, for example:
>>
>>
>> https://raw.githubusercontent.com/python/cpython/3.7/Misc/NEWS.d/3.7.4rc1.rst
>>
>> https://docs.python.org/3/whatsnew/changelog.html#python-3-7-4-release-candidate-1
>>
>> Another thing that we look for is brevity.  In general, news entries
>> should be short, ideally one to three sentences.  They should not go into
>> great detail as the point of the changelog is to provide a high-level
>> overview of the changes going into each release.  Readers interested in
>> more detail can click on the link to the bpo issue for the full discussion
>> and links to PRs and merges.
>>
>> --
>>   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 

[Python-Dev] Re: Inline links in Misc/NEWS entries

[Kyle Stanley]

> Note that there is an open devguide issue that requests improvements in
the description of news entry processing

Good to know, I'll look further into this issue and see if I can help with
it.

> In general, using many Python-specific Sphinx markup entities is fine:
browsing though the consolidated blurb files for previous releases (and the
resultant changelog html) shows uses of entities like :func: and :class:.

Since it's okay to use Python-specific Sphinx, should we encourage the
usage of it when appropriate, such as when the links could provide helpful
information to users?

The primary purpose of me creating this topic was because there seems to be
some sentiment that it's perfectly fine to exclusively use plaintext in the
news entries. Especially in cases where authors have rejected suggestions
to adding the Sphinx markup in their PRs. There seems to be some sentiment
that it's perfectly fine to exclusively use plaintext in every news entry.
Personally, I think it's a bit more nuanced, and that the links can
sometimes be very helpful for readers.

> Readers interested in more detail can click on the link to the bpo issue
for the full discussion and links to PRs and merges.

Similarly to clicking on the bpo issue, users being able to also click on
the link for functions and classes for more details also allow the news
entry to be more succinct. Especially for changes involving complex
modules, such as asyncio. But even for more simple changes, it shows newer
readers where they can find more information on the more commonly used
functions.

Also, a related question: would it be helpful for contributors to look
through news entries for the latest stable and beta releases, and add
inline links where they could be useful for readers?

I would be more than happy to help with this. A large part of the reason
why I started contributing is because I've always been very pleased with
the quality of Python's documentation and helpfulness towards newer users.
It was my first programming language 5+ years ago. My primary goals are to
further improve the documentation and other resources for newer users of
the language.

Thanks,
Kyle Stanley


On Tue, Aug 13, 2019 at 3:58 AM Ned Deily  wrote:

> On Aug 13, 2019, at 00:20, Kyle Stanley  wrote:
> > On Tue, Aug 13, 2019 at 2:41 AM Mariatta 
> wrote:
> > > I would like to understand why some developers dislike including it,
> even when the reST syntax is provided.
> >
> > This has something to do with the use of blurb/blurb-it. Both tools
> specifically say "single paragraph with simple ReST markup".
> >
> > Further reading blurb's source code, it says the format of the news
> blurb should be as follows:
> >   * The BODY section should be a single paragraph of English text
> > in ReST format.  It should not use the following ReST markup
> > features:
> >   * section headers
> >   * comments
> >   * directives, citations, or footnotes
> >   * Any features that require significant line breaks,
> > like lists, definition lists, quoted paragraphs, line blocks,
> > literal code blocks, and tables.
>
> Note that there is an open devguide issue that requests improvements in
> the description of news entry processing:
> https://github.com/python/devguide/issues/358
>
> Release managers are responsible for reviewing and editing, as necessary,
> the changelog files that are produced in the docset for each release from
> the individual blurb news items.  In general, using many Python-specific
> Sphinx markup entities is fine: browsing though the consolidated blurb
> files for previous releases (and the resultant changelog html) shows uses
> of entities like :func: and :class:.  See, for example:
>
>
> https://raw.githubusercontent.com/python/cpython/3.7/Misc/NEWS.d/3.7.4rc1.rst
>
> https://docs.python.org/3/whatsnew/changelog.html#python-3-7-4-release-candidate-1
>
> Another thing that we look for is brevity.  In general, news entries
> should be short, ideally one to three sentences.  They should not go into
> great detail as the point of the changelog is to provide a high-level
> overview of the changes going into each release.  Readers interested in
> more detail can click on the link to the bpo issue for the full discussion
> and links to PRs and merges.
>
> --
>   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/7CK6RRERHSLEZDFBT2AFRJ3N7FNUSRIX/

[Python-Dev] Re: Inline links in Misc/NEWS entries

[Ned Deily]

On Aug 13, 2019, at 00:20, Kyle Stanley  wrote:
> On Tue, Aug 13, 2019 at 2:41 AM Mariatta  wrote:
> > I would like to understand why some developers dislike including it, even 
> > when the reST syntax is provided. 
> 
> This has something to do with the use of blurb/blurb-it. Both tools 
> specifically say "single paragraph with simple ReST markup".
> 
> Further reading blurb's source code, it says the format of the news blurb 
> should be as follows:
>   * The BODY section should be a single paragraph of English text
> in ReST format.  It should not use the following ReST markup
> features:
>   * section headers
>   * comments
>   * directives, citations, or footnotes
>   * Any features that require significant line breaks,
> like lists, definition lists, quoted paragraphs, line blocks,
> literal code blocks, and tables.

Note that there is an open devguide issue that requests improvements in the 
description of news entry processing:
https://github.com/python/devguide/issues/358

Release managers are responsible for reviewing and editing, as necessary, the 
changelog files that are produced in the docset for each release from the 
individual blurb news items.  In general, using many Python-specific Sphinx 
markup entities is fine: browsing though the consolidated blurb files for 
previous releases (and the resultant changelog html) shows uses of entities 
like :func: and :class:.  See, for example:

https://raw.githubusercontent.com/python/cpython/3.7/Misc/NEWS.d/3.7.4rc1.rst
https://docs.python.org/3/whatsnew/changelog.html#python-3-7-4-release-candidate-1

Another thing that we look for is brevity.  In general, news entries should be 
short, ideally one to three sentences.  They should not go into great detail as 
the point of the changelog is to provide a high-level overview of the changes 
going into each release.  Readers interested in more detail can click on the 
link to the bpo issue for the full discussion and links to PRs and merges.

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

[Python-Dev] Re: Inline links in Misc/NEWS entries

[Kyle Stanley]

> * The BODY section should be a single paragraph of English text in ReST
format. It should not use the following ReST markup features:
> * section headers
> * comments
> * directives, citations, or footnotes
> * Any features that require significant line breaks, like lists,
definition lists, quoted paragraphs, line blocks, literal code blocks, and
tables.

As far as I can tell, the usage of inline markup for links with something
like :func:\`os.listdir\` would not be in violation of this.

Also, as a clarification, what I was describing was apparently just Sphinx,
not reST: https://devguide.python.org/documenting/#id4. For some reason, I
was under the impression that the syntax was reST and then Sphinx processed
the markup to find a matching link. I'm not certain as to whether or not
blurb supports Sphinx. If not, I wouldn't mind assisting with the process
of adding support for it, I think it's worthwhile to include inline links
when appropriate.

If not, the link could also be provided with the reST cross-link
markup: :ref:\`label\`
as long as the section has a corresponding label. This doesn't seem like it
uses any of the above restricted reST features. But if that's also an
issue, a more explicit reST hyper link could be provided with: \`Link text <
http://target>\`_. However, direct links are probably the most likely to
become deprecated or lead to dead ends, so the other options would be more
preferable for less maintenance.

Thanks,
Kyle Stanley

On Tue, Aug 13, 2019 at 2:41 AM Mariatta  wrote:

> > I would like to understand why some developers dislike including it,
> even when the reST syntax is provided.
>
> This has something to do with the use of blurb/blurb-it. Both tools
> specifically say "single paragraph with simple ReST markup".
>
> Further reading blurb's source code, it says the format of the news blurb
> should be as follows:
>
>   * The BODY section should be a single paragraph of English text
> in ReST format.  It should not use the following ReST markup
> features:
>   * section headers
>   * comments
>   * directives, citations, or footnotes
>   * Any features that require significant line breaks,
> like lists, definition lists, quoted paragraphs, line blocks,
> literal code blocks, and tables.
>
>
> Perhaps Larry has more context on why the news entry should be "simple"?
>
>
>
___
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/YTST7DKDTD3K6PIUE345J25B2CMJORLY/

[Python-Dev] Re: Inline links in Misc/NEWS entries

[Mariatta]

> I would like to understand why some developers dislike including it, even
when the reST syntax is provided.

This has something to do with the use of blurb/blurb-it. Both tools
specifically say "single paragraph with simple ReST markup".

Further reading blurb's source code, it says the format of the news blurb
should be as follows:

  * The BODY section should be a single paragraph of English text
in ReST format.  It should not use the following ReST markup
features:
  * section headers
  * comments
  * directives, citations, or footnotes
  * Any features that require significant line breaks,
like lists, definition lists, quoted paragraphs, line blocks,
literal code blocks, and tables.


Perhaps Larry has more context on why the news entry should be "simple"?
___
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/3B4HRDQH5LFT7B4SLKMGOQNN56TP5A4X/