Repository navigation
gh-101100: Fix Sphinx warnings in whatsnew/2.0.rst - #112351
hugovk merged 5 commits into
Conversation
Sorry, something went wrong.
|
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. |
Sorry, something went wrong.
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.
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? |
Sorry, something went wrong.
|
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. |
Sorry, something went wrong.
|
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'), |
Sorry, something went wrong.
terryjreedy
left a comment
There was a problem hiding this comment.
LGTM assuming that the one added path is correct.
Sorry, something went wrong.
|
Thanks @hugovk for the PR 🌮🎉.. I'm working now to backport this PR to: 3.11, 3.12. |
Sorry, something went wrong.
|
Sorry, @hugovk, I could not cleanly backport this to 3.12 due to a conflict. cherry_picker a00b41b9e9257e3c779e3ef5d5d5f0cef9223a30 3.12 |
Sorry, something went wrong.
|
Sorry, @hugovk, I could not cleanly backport this to 3.11 due to a conflict. cherry_picker a00b41b9e9257e3c779e3ef5d5d5f0cef9223a30 3.11 |
Sorry, something went wrong.
…thonGH-112351) (cherry picked from commit a00b41b) Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com>
|
GH-115902 is a backport of this pull request to the 3.12 branch. |
Sorry, something went wrong.
|
GH-115903 is a backport of this pull request to the 3.11 branch. |
Sorry, something went wrong.
…thonGH-112351) (cherry picked from commit a00b41b) Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com>
… (#115902) Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com>
… (#115903) Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com>
…2351) Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com>
…2351) Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com>
…2351) Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com>
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📚 Documentation preview 📚: https://cpython-previews--112351.org.readthedocs.build/