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