Movatterモバイル変換

[0]ホーム
URL:

Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

 Sign up
Appearance settings

gh-101100: Fix Sphinx warnings inwhatsnew/2.0.rst#112351

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to ourterms of service andprivacy statement. We’ll occasionally send you account related emails.

Already on GitHub?Sign in to your account

Merged

Conversation

hugovk
Copy link
Member

@hugovkhugovk commentedNov 23, 2023•
edited
Loading

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: readDoc/whatsnew/2.0.rst:219: WARNING: py:meth reference target not found: readlinesDoc/whatsnew/2.0.rst:224: WARNING: py:meth reference target not found: writeDoc/whatsnew/2.0.rst:224: WARNING: py:meth reference target not found: writelinesDoc/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: NumberDoc/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: stropDoc/whatsnew/2.0.rst:392: WARNING: py:mod reference target not found: stropDoc/whatsnew/2.0.rst:392: WARNING: py:func reference target not found: string.replaceDoc/whatsnew/2.0.rst:418: WARNING: py:meth reference target not found: startswithDoc/whatsnew/2.0.rst:418: WARNING: py:meth reference target not found: endswithDoc/whatsnew/2.0.rst:423: WARNING: py:meth reference target not found: joinDoc/whatsnew/2.0.rst:423: WARNING: py:meth reference target not found: joinDoc/whatsnew/2.0.rst:423: WARNING: py:func reference target not found: string.joinDoc/whatsnew/2.0.rst:504: WARNING: py:func reference target not found: applyDoc/whatsnew/2.0.rst:504: WARNING: py:func reference target not found: fDoc/whatsnew/2.0.rst:504: WARNING: py:func reference target not found: applyDoc/whatsnew/2.0.rst:518: WARNING: py:meth reference target not found: writeDoc/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: longDoc/whatsnew/2.0.rst:622: WARNING: py:meth reference target not found: getDoc/whatsnew/2.0.rst:622: WARNING: py:meth reference target not found: setdefaultDoc/whatsnew/2.0.rst:622: WARNING: py:meth reference target not found: getDoc/whatsnew/2.0.rst:656: WARNING: py:meth reference target not found: appendDoc/whatsnew/2.0.rst:656: WARNING: py:meth reference target not found: insertDoc/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_exDoc/whatsnew/2.0.rst:673: WARNING: py:func reference target not found: socket.bindDoc/whatsnew/2.0.rst:694: WARNING: py:meth reference target not found: tellDoc/whatsnew/2.0.rst:694: WARNING: py:meth reference target not found: seekDoc/whatsnew/2.0.rst:716: WARNING: py:func reference target not found: sprintfDoc/whatsnew/2.0.rst:724: WARNING: py:mod reference target not found: exceptionsDoc/whatsnew/2.0.rst:882: WARNING: py:mod reference target not found: xmllibDoc/whatsnew/2.0.rst:882: WARNING: py:mod reference target not found: xmllibDoc/whatsnew/2.0.rst:898: WARNING: py:meth reference target not found: startElementDoc/whatsnew/2.0.rst:898: WARNING: py:meth reference target not found: endElementDoc/whatsnew/2.0.rst:898: WARNING: py:meth reference target not found: charactersDoc/whatsnew/2.0.rst:942: WARNING: py:class reference target not found: DocumentDoc/whatsnew/2.0.rst:942: WARNING: py:class reference target not found: ElementDoc/whatsnew/2.0.rst:942: WARNING: py:class reference target not found: ElementDoc/whatsnew/2.0.rst:956: WARNING: py:func reference target not found: parseDoc/whatsnew/2.0.rst:956: WARNING: py:func reference target not found: parseStringDoc/whatsnew/2.0.rst:964: WARNING: py:class reference target not found: DocumentDoc/whatsnew/2.0.rst:964: WARNING: py:class reference target not found: DocumentDoc/whatsnew/2.0.rst:964: WARNING: py:class reference target not found: ElementDoc/whatsnew/2.0.rst:964: WARNING: py:class reference target not found: NodeDoc/whatsnew/2.0.rst:964: WARNING: py:meth reference target not found: toxmlDoc/whatsnew/2.0.rst:964: WARNING: py:class reference target not found: ElementDoc/whatsnew/2.0.rst:964: WARNING: py:class reference target not found: DocumentDoc/whatsnew/2.0.rst:997: WARNING: py:class reference target not found: NodeDoc/whatsnew/2.0.rst:1023: WARNING: py:mod reference target not found: sgmlopDoc/whatsnew/2.0.rst:1031: WARNING: py:mod reference target not found: ConfigParserDoc/whatsnew/2.0.rst:1031: WARNING: py:mod reference target not found: xmllibDoc/whatsnew/2.0.rst:1037: WARNING: py:mod reference target not found: httplibDoc/whatsnew/2.0.rst:1046: WARNING: py:mod reference target not found: httplibDoc/whatsnew/2.0.rst:1046: WARNING: py:mod reference target not found: httplibDoc/whatsnew/2.0.rst:1051: WARNING: py:mod reference target not found: TkinterDoc/whatsnew/2.0.rst:1086: WARNING: py:mod reference target not found: encodingsDoc/whatsnew/2.0.rst:1089: WARNING: py:mod reference target not found: cmpDoc/whatsnew/2.0.rst:1089: WARNING: py:mod reference target not found: cmpcacheDoc/whatsnew/2.0.rst:1089: WARNING: py:mod reference target not found: dircmpDoc/whatsnew/2.0.rst:1098: WARNING: py:mod reference target not found: linuxaudiodevDoc/whatsnew/2.0.rst:1098: WARNING: py:mod reference target not found: sunaudiodevDoc/whatsnew/2.0.rst:1108: WARNING: py:mod reference target not found: pyexpatDoc/whatsnew/2.0.rst:1111: WARNING: py:mod reference target not found: robotparserDoc/whatsnew/2.0.rst:1120: WARNING: py:mod reference target not found: UserStringDoc/whatsnew/2.0.rst:1132: WARNING: py:mod reference target not found: _winregDoc/whatsnew/2.0.rst:1132: WARNING: py:mod reference target not found: _winregDoc/whatsnew/2.0.rst:1132: WARNING: py:mod reference target not found: _winregDoc/whatsnew/2.0.rst:1142: WARNING: py:mod reference target not found: imputilDoc/whatsnew/2.0.rst:1142: WARNING: py:mod reference target not found: ihooksDoc/whatsnew/2.0.rst:1186: WARNING: py:mod reference target not found: stdwinDoc/whatsnew/2.0.rst:1190: WARNING: py:mod reference target not found: cmpDoc/whatsnew/2.0.rst:1190: WARNING: py:mod reference target not found: cmpcacheDoc/whatsnew/2.0.rst:1190: WARNING: py:mod reference target not found: dircmpDoc/whatsnew/2.0.rst:1190: WARNING: py:mod reference target not found: dumpDoc/whatsnew/2.0.rst:1190: WARNING: py:mod reference target not found: findDoc/whatsnew/2.0.rst:1190: WARNING: py:mod reference target not found: grepDoc/whatsnew/2.0.rst:1190: WARNING: py:mod reference target not found: packmailDoc/whatsnew/2.0.rst:1190: WARNING: py:mod reference target not found: polyDoc/whatsnew/2.0.rst:1190: WARNING: py:mod reference target not found: utilDoc/whatsnew/2.0.rst:1190: WARNING: py:mod reference target not found: whatsoundDoc/whatsnew/2.0.rst:1190: WARNING: py:mod reference target not found: zmod

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

@hugovkhugovk changed the titlegh-101100: Silence Sphinx warnings inwhatsnew/2.0.rstgh-101100: Fix Sphinx warnings inwhatsnew/2.0.rstNov 24, 2023
@hugovkhugovk added the docsDocumentation in the Doc dir labelNov 24, 2023
@serhiy-storchaka
Copy link
Member

It may be easier to just keep these files inDoc/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
Copy link
MemberAuthor

It may be easier to just keep these files inDoc/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 inbuild/NEWS
  • 1,992 inwhatsnew/*
    • 1,356 inwhatsnew/2.*
    • 467 inwhatsnew/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 innitpick_ignore, then each is a single line addition toconf.py and we don't need to change all the other RST files. What do you think?

@serhiy-storchaka
Copy link
Member

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 likereadline,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
Copy link
MemberAuthor

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'),

Copy link
Member

@terryjreedyterryjreedy left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

LGTM assuming that the one added path is correct.

@hugovkhugovk merged commita00b41b intopython:mainFeb 25, 2024
@hugovkhugovk deleted the docs-fix-sphinx-warnings-whatsnew-2.0 branchFebruary 25, 2024 09:45
@miss-islington-app
Copy link

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

@miss-islington-app
Copy link

Sorry,@hugovk, I could not cleanly backport this to3.12 due to a conflict.
Please backport usingcherry_picker on command line.

cherry_picker a00b41b9e9257e3c779e3ef5d5d5f0cef9223a30 3.12

@miss-islington-app
Copy link

Sorry,@hugovk, I could not cleanly backport this to3.11 due to a conflict.
Please backport usingcherry_picker on command line.

cherry_picker a00b41b9e9257e3c779e3ef5d5d5f0cef9223a30 3.11

hugovk added a commit to hugovk/cpython that referenced this pull requestFeb 25, 2024
…thonGH-112351)(cherry picked from commita00b41b)Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com>
@bedevere-app
Copy link

GH-115902 is a backport of this pull request to the3.12 branch.

@bedevere-appbedevere-appbot removed the needs backport to 3.12only security fixes labelFeb 25, 2024
@bedevere-app
Copy link

GH-115903 is a backport of this pull request to the3.11 branch.

@bedevere-appbedevere-appbot removed the needs backport to 3.11only security fixes labelFeb 25, 2024
hugovk added a commit to hugovk/cpython that referenced this pull requestFeb 25, 2024
…thonGH-112351)(cherry picked from commita00b41b)Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com>
hugovk added a commit that referenced this pull requestFeb 25, 2024
… (#115902)Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com>
hugovk added a commit that referenced this pull requestFeb 25, 2024
… (#115903)Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com>
woodruffw pushed a commit to woodruffw-forks/cpython that referenced this pull requestMar 4, 2024
…2351)Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com>
diegorusso pushed a commit to diegorusso/cpython that referenced this pull requestApr 17, 2024
…2351)Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com>
LukasWoodtli pushed a commit to LukasWoodtli/cpython that referenced this pull requestJan 22, 2025
…2351)Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com>
Sign up for freeto join this conversation on GitHub. Already have an account?Sign in to comment
Reviewers

@terryjreedyterryjreedyterryjreedy approved these changes

Assignees

@hugovkhugovk

Labels
docsDocumentation in the Doc dirskip news
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.

3 participants
@hugovk@serhiy-storchaka@terryjreedy
[8]ページ先頭
©2009-2025 Movatter.jp