Fixes and improvements to 3.8 whatsnew

[aeros]

This PR is mostly focused on repairing broken Sphinx roles that weren't correctly generating links, but also adds a few new ones and shortens some of the longer ones using ~. It also includes a few minor grammar corrections and improvements.

For comparison, see https://docs.python.org/3.8/whatsnew/3.8.html and build the html locally from this PR. I've verified each of the Sphinx roles that I added locally to ensure the links were properly generated.

Also, is there an easy way to add myself to Misc/ACKS just for 3.8 without opening a separate PR? I added in an entry for myself in 3.9 several months ago, but never did it for 3.8. I've had several merged PRs that were backported to 3.8. I was thinking that it might be possible to add it to the backport PR.

[aeros]

Thanks for feedback @JelleZijlstra.

[aeros]

Thanks for the feedback @merwok.

[aeros]

Correcting that recently added Sphinx role, it should be

:term:`dictionary views <dictionary view>`

instead of

:term:`dictionary view`s

[aeros]

@rhettinger Will you have time to look this over in the next week or so? Since @ambv has the release date for 3.8 planned on October 14th, we should probably try to wrap this up before October 12th to avoid last minute additions.

[rhettinger]

I don't think most of these should be done and they will get in the way of the more substantive edits currently in progress.

[aeros]

@rhettinger

I don't think most of these should be done and they will get in the way of the more substantive edits currently in progress.

This PR was primarily made because of @ambv's announcement in python-dev for 3.8.0rc1, specifically the request for helping with the "What's New" document:

Can you help with the “What’s New” document?

As someone who has become highly familiar with using Sphinx roles from other contributions I've made to the documentation and the devguide, I found that I was able to help fix many of the currently broken inline links and add a few useful new ones. Those links can be quite useful for readers to easily navigate to a page for finding more information on a given topic. It's not always straightforward for readers to find the correct location if they're not familiar with the structure of the documentation and the search feature is not always reliable.

I'm aware that they are not as important as the entries themselves, but they certainly have some "substantive" value. I also spent a substantial amount of time reviewing these changes to make sure the ones that were fixed or added were rendering properly and linking to the current location by building the documentation locally, in addition to finding the broken ones in the first place.

Also, I feel like I've been getting rather mixed and inconsistent messages regarding the importance and usage of Sphinx roles. From the thread that I created in python-dev regarding Sphinx roles in addition to other conversations with core developers, my impression has been that the most valuable locations to have them in is "What's New" and the docs due to the volume of readers. Since then, I haven't emphasized on adding them for individual Misc/NEWS entries, as I was in the past. Recently, I've only been concerned with fixing them in the actual docs and "What's New". Personally, I think that if we're going to use them, we should do so correctly.

The impression I'm getting here though is that these changes would be getting in the way of more substantial ones. If this is correct, I am willing to accept that and can focus my efforts on other areas, such as asyncio.

But, I would highly appreciate it if we could have a clear message on this so that I'm not just spending a portion my available time tidying up "What's New" entries, only for it to be essentially said that my efforts would be getting in the way. I was previously under the impression that it would be fairly important to not have broken inline links in the "What's New" for 3.8, considering that the release is scheduled to be coming up in a couple of days.

Edit: Also, I wanted to mention that I have no issue with resolving the merge conflicts and waiting to add these changes until after the other ones are finished.

[ncoghlan]

@rhettinger There are a number of PRs that have been merged for What's New in the past few days, and you've removed the draft status. Does that mean @aeros can go ahead with resolving the merge conflicts with this PR, and we can discuss any remaining concerns with the specific proposed changes?

[rhettinger]

I don't want to go forward with this for a while. Many of the markup changes are debatable and are mostly non-substantive. Also, there is excess mark-up that isn't necessary or desirable in Whatsnew (we don't have to link every term to the glossary or every mention of dict to the dict class -- those may be important elsewhere but less so in this document). FWIW, there are other edits in process that should be finished before creating any more potential merge conflicts. Also, it takes a lot of time to individually discuss every micro-edit, especially when stylistic changes are at the editors discretion. The kind of contribution that would be most useful at this point would be better examples for the parts I haven't touched yet (for example, I am meeting soon with Davin to come up with a meaningful and correct example for multiprocessing shared memory).

[rhettinger]

FWIW, some of these were helpful. I moved the useful ones into my latest PR so as to avoid continuing merge conflicts and so that I could see the markup effects one by one. See #16854

Marking this a closed.

[aeros]

@rhettinger

Also, there is excess mark-up that isn't necessary or desirable in Whatsnew (we don't have to link every term to the glossary or every mention of dict to the dict class -- those may be important elsewhere but less so in this document).

I primarily focused on doing so for terms that had links to the glossary in other sections and when it seemed relevant. But I can understand the general sentiment that excessive inline links can be distracting. Was this the primary issue with the PR? If not, could you elaborate on some of the other general issues without having to point to all of the specifics? This would help me with future PRs to What's New.

FWIW, some of these were helpful. I moved the useful ones into my latest PR so as to avoid continuing merge conflicts and so that I could see the markup effects one by one. See #16854

That's good to hear at least, I'm glad that some of the changes were useful. Would you mind either adding me to the "Co-Authored-By" in the commit or @mentioning me in the PR itself?

[ncoghlan]

What's New sections are often linked to directly, so a useful policy to follow is "Link a term the first time it is mentioned in a section, but don't link the second and subsequent references".

(That policy is actually generally useful throughout all the documentation, since it's pretty rare for anyone to read entire pages top to bottom - they're more commonly following a link to a specific section or API header)