> 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 <wes.tur...@gmail.com> 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 <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/4UIY6UDE6V2TEKN2CY6EXJG5MITXIQFJ/
