gh-101100: Fix Sphinx warnings in whatsnew/2.0.rst

[hugovk]

On the one hand, we don't want to spend time fixing the old What's New files.

But on the other, the ultimate aim of #101100 is to turn all warnings into errors, which means these files need tackling.

To balance this, let's do the minimum needed, and fix these 87 warnings by silencing with the ! or fix them if it's straightforward.

Doc/whatsnew/2.0.rst:219: WARNING: py:meth reference target not found: read
Doc/whatsnew/2.0.rst:219: WARNING: py:meth reference target not found: readlines
Doc/whatsnew/2.0.rst:224: WARNING: py:meth reference target not found: write
Doc/whatsnew/2.0.rst:224: WARNING: py:meth reference target not found: writelines
Doc/whatsnew/2.0.rst:356: WARNING: py:meth reference target not found: __iadd__
Doc/whatsnew/2.0.rst:356: WARNING: py:meth reference target not found: __isub__
Doc/whatsnew/2.0.rst:356: WARNING: py:class reference target not found: Number
Doc/whatsnew/2.0.rst:377: WARNING: py:meth reference target not found: __iadd__
Doc/whatsnew/2.0.rst:392: WARNING: py:mod reference target not found: strop
Doc/whatsnew/2.0.rst:392: WARNING: py:mod reference target not found: strop
Doc/whatsnew/2.0.rst:392: WARNING: py:func reference target not found: string.replace
Doc/whatsnew/2.0.rst:418: WARNING: py:meth reference target not found: startswith
Doc/whatsnew/2.0.rst:418: WARNING: py:meth reference target not found: endswith
Doc/whatsnew/2.0.rst:423: WARNING: py:meth reference target not found: join
Doc/whatsnew/2.0.rst:423: WARNING: py:meth reference target not found: join
Doc/whatsnew/2.0.rst:423: WARNING: py:func reference target not found: string.join
Doc/whatsnew/2.0.rst:504: WARNING: py:func reference target not found: apply
Doc/whatsnew/2.0.rst:504: WARNING: py:func reference target not found: f
Doc/whatsnew/2.0.rst:504: WARNING: py:func reference target not found: apply
Doc/whatsnew/2.0.rst:518: WARNING: py:meth reference target not found: write
Doc/whatsnew/2.0.rst:538: WARNING: py:meth reference target not found: __contains__
Doc/whatsnew/2.0.rst:559: WARNING: py:meth reference target not found: __cmp__
Doc/whatsnew/2.0.rst:610: WARNING: py:func reference target not found: long
Doc/whatsnew/2.0.rst:622: WARNING: py:meth reference target not found: get
Doc/whatsnew/2.0.rst:622: WARNING: py:meth reference target not found: setdefault
Doc/whatsnew/2.0.rst:622: WARNING: py:meth reference target not found: get
Doc/whatsnew/2.0.rst:656: WARNING: py:meth reference target not found: append
Doc/whatsnew/2.0.rst:656: WARNING: py:meth reference target not found: insert
Doc/whatsnew/2.0.rst:673: WARNING: py:func reference target not found: socket.connect( ('hostname', 25) )
Doc/whatsnew/2.0.rst:673: WARNING: py:func reference target not found: socket.connect(
Doc/whatsnew/2.0.rst:673: WARNING: py:func reference target not found: socket.connect_ex
Doc/whatsnew/2.0.rst:673: WARNING: py:func reference target not found: socket.bind
Doc/whatsnew/2.0.rst:694: WARNING: py:meth reference target not found: tell
Doc/whatsnew/2.0.rst:694: WARNING: py:meth reference target not found: seek
Doc/whatsnew/2.0.rst:716: WARNING: py:func reference target not found: sprintf
Doc/whatsnew/2.0.rst:724: WARNING: py:mod reference target not found: exceptions
Doc/whatsnew/2.0.rst:882: WARNING: py:mod reference target not found: xmllib
Doc/whatsnew/2.0.rst:882: WARNING: py:mod reference target not found: xmllib
Doc/whatsnew/2.0.rst:898: WARNING: py:meth reference target not found: startElement
Doc/whatsnew/2.0.rst:898: WARNING: py:meth reference target not found: endElement
Doc/whatsnew/2.0.rst:898: WARNING: py:meth reference target not found: characters
Doc/whatsnew/2.0.rst:942: WARNING: py:class reference target not found: Document
Doc/whatsnew/2.0.rst:942: WARNING: py:class reference target not found: Element
Doc/whatsnew/2.0.rst:942: WARNING: py:class reference target not found: Element
Doc/whatsnew/2.0.rst:956: WARNING: py:func reference target not found: parse
Doc/whatsnew/2.0.rst:956: WARNING: py:func reference target not found: parseString
Doc/whatsnew/2.0.rst:964: WARNING: py:class reference target not found: Document
Doc/whatsnew/2.0.rst:964: WARNING: py:class reference target not found: Document
Doc/whatsnew/2.0.rst:964: WARNING: py:class reference target not found: Element
Doc/whatsnew/2.0.rst:964: WARNING: py:class reference target not found: Node
Doc/whatsnew/2.0.rst:964: WARNING: py:meth reference target not found: toxml
Doc/whatsnew/2.0.rst:964: WARNING: py:class reference target not found: Element
Doc/whatsnew/2.0.rst:964: WARNING: py:class reference target not found: Document
Doc/whatsnew/2.0.rst:997: WARNING: py:class reference target not found: Node
Doc/whatsnew/2.0.rst:1023: WARNING: py:mod reference target not found: sgmlop
Doc/whatsnew/2.0.rst:1031: WARNING: py:mod reference target not found: ConfigParser
Doc/whatsnew/2.0.rst:1031: WARNING: py:mod reference target not found: xmllib
Doc/whatsnew/2.0.rst:1037: WARNING: py:mod reference target not found: httplib
Doc/whatsnew/2.0.rst:1046: WARNING: py:mod reference target not found: httplib
Doc/whatsnew/2.0.rst:1046: WARNING: py:mod reference target not found: httplib
Doc/whatsnew/2.0.rst:1051: WARNING: py:mod reference target not found: Tkinter
Doc/whatsnew/2.0.rst:1086: WARNING: py:mod reference target not found: encodings
Doc/whatsnew/2.0.rst:1089: WARNING: py:mod reference target not found: cmp
Doc/whatsnew/2.0.rst:1089: WARNING: py:mod reference target not found: cmpcache
Doc/whatsnew/2.0.rst:1089: WARNING: py:mod reference target not found: dircmp
Doc/whatsnew/2.0.rst:1098: WARNING: py:mod reference target not found: linuxaudiodev
Doc/whatsnew/2.0.rst:1098: WARNING: py:mod reference target not found: sunaudiodev
Doc/whatsnew/2.0.rst:1108: WARNING: py:mod reference target not found: pyexpat
Doc/whatsnew/2.0.rst:1111: WARNING: py:mod reference target not found: robotparser
Doc/whatsnew/2.0.rst:1120: WARNING: py:mod reference target not found: UserString
Doc/whatsnew/2.0.rst:1132: WARNING: py:mod reference target not found: _winreg
Doc/whatsnew/2.0.rst:1132: WARNING: py:mod reference target not found: _winreg
Doc/whatsnew/2.0.rst:1132: WARNING: py:mod reference target not found: _winreg
Doc/whatsnew/2.0.rst:1142: WARNING: py:mod reference target not found: imputil
Doc/whatsnew/2.0.rst:1142: WARNING: py:mod reference target not found: ihooks
Doc/whatsnew/2.0.rst:1186: WARNING: py:mod reference target not found: stdwin
Doc/whatsnew/2.0.rst:1190: WARNING: py:mod reference target not found: cmp
Doc/whatsnew/2.0.rst:1190: WARNING: py:mod reference target not found: cmpcache
Doc/whatsnew/2.0.rst:1190: WARNING: py:mod reference target not found: dircmp
Doc/whatsnew/2.0.rst:1190: WARNING: py:mod reference target not found: dump
Doc/whatsnew/2.0.rst:1190: WARNING: py:mod reference target not found: find
Doc/whatsnew/2.0.rst:1190: WARNING: py:mod reference target not found: grep
Doc/whatsnew/2.0.rst:1190: WARNING: py:mod reference target not found: packmail
Doc/whatsnew/2.0.rst:1190: WARNING: py:mod reference target not found: poly
Doc/whatsnew/2.0.rst:1190: WARNING: py:mod reference target not found: util
Doc/whatsnew/2.0.rst:1190: WARNING: py:mod reference target not found: whatsound
Doc/whatsnew/2.0.rst:1190: WARNING: py:mod reference target not found: zmod

• Issue: Fix all Sphinx reference warnings in the documentation #101100

---

📚 Documentation preview 📚: https://cpython-previews--112351.org.readthedocs.build/

[serhiy-storchaka]

It may be easier to just keep these files in Doc/tools/.nitignore indefinitely. The aim is not to silence all warnings, the aim is to fix existing errors and prevent future errors.

There may be a lot of dead references in the old Changelog. If we do not want to rewrite them every time some API is deprecated and removed, we can just ignore warnings in old files.

[hugovk]

It may be easier to just keep these files in Doc/tools/.nitignore indefinitely. The aim is not to silence all warnings, the aim is to fix existing errors and prevent future errors.

I would like to eventually remove the custom .nitignore tooling, and we can run Sphinx with -W (turn warnings into errors) without having to post-process an output file.

To get to the clean slate, we can fix or ignore warnings in old files. CAM suggested adding functionality to Sphinx to be able to ignore warnings in given files, which could work, but that functionality doesn't exist yet, and our Sphinx version pin is lagging to help distros.

For really old files that aren't read much, I think it's fine to ignore the warnings that aren't trivially fixable.

There may be a lot of dead references in the old Changelog.

• 956 in build/NEWS
• 1,992 in whatsnew/*
  • 1,356 in whatsnew/2.*
  • 467 in whatsnew/3.[0-6]

If we do not want to rewrite them every time some API is deprecated and removed, we can just ignore warnings in old files.

Anyway, I think it would be a good idea to blanket ignore deprecations/removals in nitpick_ignore, then each is a single line addition to conf.py and we don't need to change all the other RST files. What do you think?

[serhiy-storchaka]

Blindly ignoring warnings can hide real errors. Adding outdated Python 2 and Python 1 names to the ignore list will ignore them in all other files, where they perhaps should not be ignored. Also it can conflict with existing names.

Names like readline, write, __iadd__, startswith, setdefault, etc, etc should not be ignored. They are actual methods, and they can be turned into valid references. Other side, it is not easy to provide references for them, because they are not declared with the .. method:: directive, they are described in less formal way. There are other broken references to these methods in other files, and they should be fixed once we find a way to create a reference to the name without using the corresponding directive. Sphinx 7.2 may have an option that helps with this (:no-typesetting:, but I did not test it), but we are far from picking this version.

[hugovk]

Yes, I'd recommend only ignoring removed modules:

    ('py:mod', 'cPickle'),
    ('py:mod', 'sunaudiodev'),

Or other things that are fully qualified, like:

    ('py:meth', 'unittest.TestCase.assertDictContainsSubset'),

[terryjreedy]

LGTM assuming that the one added path is correct.

[miss-islington-app]

Thanks @hugovk for the PR 🌮🎉.. I'm working now to backport this PR to: 3.11, 3.12.
🐍🍒⛏🤖

[miss-islington-app]

Sorry, @hugovk, I could not cleanly backport this to 3.12 due to a conflict.
Please backport using cherry_picker on command line.

cherry_picker a00b41b9e9257e3c779e3ef5d5d5f0cef9223a30 3.12

[miss-islington-app]

Sorry, @hugovk, I could not cleanly backport this to 3.11 due to a conflict.
Please backport using cherry_picker on command line.

cherry_picker a00b41b9e9257e3c779e3ef5d5d5f0cef9223a30 3.11

[bedevere-app]

GH-115902 is a backport of this pull request to the 3.12 branch.

[bedevere-app]

GH-115903 is a backport of this pull request to the 3.11 branch.