> The ability to effectively use Python-specific Sphinx features in NEWS entries is a relatively new feature
Ah, I think that would likely explain some of the inconsistent responses then. I think it would be worthwhile to add an example of using Sphinx and a brief explanation of when it can be useful in news entries. This would likely help improve awareness of the feature. > 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. I would definitely agree that at some point, it could end up being a bit overkill (especially for further back versions). However, with regards to prioritizing different projects, such as tidying news entries vs fixing bugs, I think a large part of that comes down to each developer's personal priorities. Also, from my experience, PRs which involve tidying up documentation have a tendency to be a bit easier to review, so in general they would end up being less time consuming anyways. Also, thanks for the tips! I'll definitely look into helping with this. Thanks, Kyle Stanley On Tue, Aug 13, 2019 at 7:30 PM 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/SSNKSLSCN5GQ5Z27235VVXA5UBFTU3YW/
