> There seems to be some sentiment that it's perfectly fine to exclusively use plaintext in every news entry.
Oops, that third sentence was a typo, I didn't intend to repeat myself there. On Tue, Aug 13, 2019 at 6:31 PM Kyle Stanley <aeros...@gmail.com> wrote: > > Note that there is an open devguide issue that requests improvements in > the description of news entry processing > > Good to know, I'll look further into this issue and see if I can help with > it. > > > 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. > > > Readers interested in more detail can click on the link to the bpo issue > for the full discussion and links to PRs and merges. > > Similarly to clicking on the bpo issue, users being able to also click on > the link for functions and classes for more details also allow the news > entry to be more succinct. Especially for changes involving complex > modules, such as asyncio. But even for more simple changes, it shows newer > readers where they can find more information on the more commonly used > functions. > > 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? > > I would be more than happy to help with this. A large part of the reason > why I started contributing is because I've always been very pleased with > the quality of Python's documentation and helpfulness towards newer users. > It was my first programming language 5+ years ago. My primary goals are to > further improve the documentation and other resources for newer users of > the language. > > Thanks, > Kyle Stanley > > > On Tue, Aug 13, 2019 at 3:58 AM Ned Deily <n...@python.org> wrote: > >> On Aug 13, 2019, at 00:20, Kyle Stanley <aeros...@gmail.com> wrote: >> > On Tue, Aug 13, 2019 at 2:41 AM Mariatta <mariatta.wij...@gmail.com> >> wrote: >> > > I would like to understand why some developers dislike including it, >> even when the reST syntax is provided. >> > >> > This has something to do with the use of blurb/blurb-it. Both tools >> specifically say "single paragraph with simple ReST markup". >> > >> > Further reading blurb's source code, it says the format of the news >> blurb should be as follows: >> > * The BODY section should be a single paragraph of English text >> > in ReST format. It should not use the following ReST markup >> > features: >> > * section headers >> > * comments >> > * directives, citations, or footnotes >> > * Any features that require significant line breaks, >> > like lists, definition lists, quoted paragraphs, line blocks, >> > literal code blocks, and tables. >> >> Note that there is an open devguide issue that requests improvements in >> the description of news entry processing: >> https://github.com/python/devguide/issues/358 >> >> Release managers are responsible for reviewing and editing, as necessary, >> the changelog files that are produced in the docset for each release from >> the individual blurb news items. 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:. See, for example: >> >> >> https://raw.githubusercontent.com/python/cpython/3.7/Misc/NEWS.d/3.7.4rc1.rst >> >> https://docs.python.org/3/whatsnew/changelog.html#python-3-7-4-release-candidate-1 >> >> Another thing that we look for is brevity. In general, news entries >> should be short, ideally one to three sentences. They should not go into >> great detail as the point of the changelog is to provide a high-level >> overview of the changes going into each release. Readers interested in >> more detail can click on the link to the bpo issue for the full discussion >> and links to PRs and merges. >> >> -- >> 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/S7GEWZGOUBZEMWXFBVSDAIPG7A6DTNKR/
