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 <aeros...@gmail.com> 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 <tjre...@udel.edu> 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/
