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 <n...@python.org> wrote: > 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/ >
_______________________________________________ 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/
