> 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 <talei...@gmail.com> 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 <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/364ZTYB5WH3YITSHR7CCFGDGCBSDQ4LJ/
