Abstract:
In general, should Misc/NEWS entries in PRs aim to provide links to documentation related to the changes made using inline reST markup?
Context:
So far in my experience over the last couple of months of reviewing PRs, I’ve noticed that there seems to be a decent amount of inconsistency across PRs when it comes to news entries. Particularly with regards to whether or not they should include relevant documentation links related to the changes made. But, this also applies to the usage of reST and Sphinx in general.
From my understanding, news entries are supposed to be somewhat up to the PR author to decide whether or not to include them, and the choice in formatting. However, I think a large part of why many authors don’t use reST markup in them is because they are not overly familiar with, not interested in, or don’t see the value in the reST syntax, so they prefer the simplicity of plain text. As far as I’m aware, there was a time when the news entries were exclusively plain text.
While I think the authors should still be given a good amount of flexibility, I think it is also important to ensure that readers of any level of experience can easily locate a source for more information on the changes. Especially if someone familiar with the reST syntax provides the exact changes for the author to make.
To those of us who are familiar with the structure of the documentation, it can be quite easy to locate the latest relevant information. However, for those who are less familiar with docs.python.org or are relying on an external search engine, they are frequently led to either the 2.7 docs or an incorrect page. Providing an inline link ensures that any curious readers can easily find more information on the changes made, regardless of their level of experience.
Example:
Inline links can be added with rather minimal effort by using reST and Sphinx (which the news entries already support) to provide a link to the documentation for a particular function, method, or class [1].
As a hypothetical example, let’s say a PR were to provide a fix to os.getcwd(), where it inappropriately raised an exception when certain characters appeared in a directory name. Here’s the news entry without the inline markup:
os.getcwd() no longer inapproriately raises an exception when …
To provide a link, we can simply use the reST role func:
:func:`os.getcwd` no longer inappropriately raises an exception when …
After being processed by Sphinx, ":func:`os.getcwd` turns into os.getcwd(), allowing users to easily find the latest relevant documentation on the function in a single click.
In this simple example, the documentation for os.getcwd() likely would remain the same, but it does allow readers who may be unfamiliar with the function to easily find out what it does. Also, for more complex changes that involve adding a new section to the docs, readers can click the link for information beyond what the news entry provides.
Motivation:
Although this is a rather simple feature that many news entries already include, the reason why I started this topic is because there have been multiple times when I’ve suggested for a PR author to include the markup (with the exact changes provided), but they decide against doing so.
I’m trying to understand the reasons as to why they don’t want to include the inline markup. From my perspective, it provides QoL to readers without any cost to readability and has minimal effort required. Particularly in cases when someone else provides the reST syntax for them.
Also, the devguide does not state whether or not this is recommended to do. The example provided only shows the usage of code-block markup:
Fix warning message when ``os.chdir()`` fails inside
``test.support.temp_cwd()``. Patch by Chris Jerdonek.
I would suggest that the documentation should at least include an example of using inline reST links in the news entry, so that authors are aware of it. Also, if the consensus is that news entries should attempt to provide documentation links when appropriate, the relevant devguide section should recommend doing so. I wouldn’t mind updating it myself, but I think it would be appropriate to gather feedback before making any changes.
[1] - There are more roles beyond function, method, and class, such as term and exception, but I wanted to keep the example as simple as possible.
, so I don’t know how much of this was a cognizant decision to carry forward).