[Python-Dev] Re: Inline links in Misc/NEWS entries

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 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 wrote:

...

On Aug 13, 2019, at 00:20, Kyle Stanley wrote:

...

On Tue, Aug 13, 2019 at 2:41 AM Mariatta 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.rs...

https://docs.python.org/3/whatsnew/changelog.html#python-3-7-4-release-candi...

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 nad@python.org -- []