Based on the feedback from the ML thread and Discuss topic, I created a new PR on python/devguide which expands the "What's New and News Entries" section of "committing.rst" to include Sphinx roles: https://github.com/python/devguide/pull/525/files

I would greatly appreciate feedback from contributors and developers less experienced with documentation to ensure that the section is easy to understand for the intended target audience. Also, review from those who are experienced with documentation and news entries is needed to ensure it is as accurate as possible.

Thanks,
Kyle Stanley

On Mon, Aug 12, 2019 at 10:24 PM Kyle Stanley <aeros167@gmail.com> wrote:
Recently, on Discuss, I created a new topic: https://discuss.python.org/t/should-news-entries-contain-documentation-links/2127

However, many may not have the time to read the full post or don’t regularly check the core workflow category on Discuss, so I'll provide a shortened version here.

During my experience thus far reviewing PRs on GitHub, I've noticed a significant degree of inconsistency when it comes to the usage of inline links with reST and Sphinx in Misc/NEWS entries. Since many of my contributions have involved documentation changes, I've familiarized myself most of the syntax.

Many of the features in markup languages provide visual modifications rather than functional ones. However, with the inline markup supported by reST and processing from Sphinx, there's a functional improvement as well. For example, the usage of :func:\`<function name>\` (escaped for mailman) provides a link to the relevant docs for the function.

In the context of news entries, this allows readers to click on a function, method, class, etc for more information. This can be useful if it's something they're not familiar with, or when the changes affected the docs. For those who are familiar with the structure of docs.python.org, the cross link to the docs may not seem at all necessary.

However, for readers that are either newer or not familiar with the structure, they might be led astray into 2.7 docs or an entirely wrong page. This happens especially frequently when using external search engines.

I'm not at all suggesting that every PR author should be required to use it or know all of the reST constructs. However, I would like for everyone to be aware of the potential usefulness of including inline links in news entries, and mention it in the devguide.

Also, I would like to understand why some developers dislike including it, even when the reST syntax is provided. The majority of authors so far would add my suggestion to their PR, but there have been some that don't want anything besides plaintext in their news entry.

Personally, I think it provides further inclusiveness to readers of all levels of experience and QoL at a very minimal cost.
_______________________________________________
Python-Dev mailing list -- python-dev@python.org
To unsubscribe send an email to python-dev-leave@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/HTAFGTQIZJQUCU6QCVF3KFD3VFGFOBWV/