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/JOMQABYA5QEQG5L6WXQJT3LXU2GF7UX4/
