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 <aeros...@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-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/ >
_______________________________________________ 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/2VI4OZI7YTFUXW4LUETY3QYZ3TU6BU7J/
