On Aug 13, 2019, at 15:31, Kyle Stanley <aeros...@gmail.com> 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/
