Skip to content

gh-101100: Fix sphinx warnings in Doc/library/functools.rst #136424

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.

Sign up for GitHub

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

Already on GitHub? Sign in to your account

Jump to bottom
Merged
merged 11 commits into from
Jul 11, 2025
Merged

gh-101100: Fix sphinx warnings in Doc/library/functools.rst #136424

merged 11 commits into from
Jul 11, 2025
+21 −13

Conversation

LamentXU123
Copy link
Contributor

@LamentXU123 LamentXU123 commented Jul 8, 2025 •
edited
Loading

before:

C:\Users\admin\Downloads\cpython-main\Doc\library\functools.rst:202: WARNING: py:func reference target not found: cache_info [ref.func]
C:\Users\admin\Downloads\cpython-main\Doc\library\functools.rst:207: WARNING: py:func reference target not found: cache_clear [ref.func]
C:\Users\admin\Downloads\cpython-main\Doc\library\functools.rst:287: WARNING: py:meth reference target not found: __lt__ [ref.meth]
C:\Users\admin\Downloads\cpython-main\Doc\library\functools.rst:287: WARNING: py:meth reference target not found: __le__ [ref.meth]
C:\Users\admin\Downloads\cpython-main\Doc\library\functools.rst:287: WARNING: py:meth reference target not found: __gt__ [ref.meth]
C:\Users\admin\Downloads\cpython-main\Doc\library\functools.rst:287: WARNING: py:meth reference target not found: __ge__ [ref.meth]
C:\Users\admin\Downloads\cpython-main\Doc\library\functools.rst:287: WARNING: py:meth reference target not found: __eq__ [ref.meth]
C:\Users\admin\Downloads\cpython-main\Doc\library\functools.rst:420: WARNING: py:func reference target not found: abstractmethod [ref.func]
C:\Users\admin\Downloads\cpython-main\Doc\library\functools.rst:502: WARNING: py:func reference target not found: register [ref.func]
C:\Users\admin\Downloads\cpython-main\Doc\library\functools.rst:567: WARNING: py:func reference target not found: register [ref.func]
C:\Users\admin\Downloads\cpython-main\Doc\library\functools.rst:575: WARNING: py:func reference target not found: register [ref.func]
C:\Users\admin\Downloads\cpython-main\Doc\library\functools.rst:653: WARNING: py:func reference target not found: register [ref.func]
C:\Users\admin\Downloads\cpython-main\Doc\library\functools.rst:656: WARNING: py:func reference target not found: register [ref.func]
C:\Users\admin\Downloads\cpython-main\Doc\library\functools.rst:785: WARNING: py:func reference target not found: example [ref.func]

This PR fix them all, I will explain all my changes:

  • link to cache_info and cache_clear are subpressed. Same to the formar subpressed link cache_parameters Create an index entries and anchor of cache_info and cache_clear
  • __lt__ , __le__, __gt__, __ge__, __eq__ are magic methods of object. So It's changed to ~object.__lt__, etc.
  • abstractmethod is actually referring to abc.abstractmethod. So it's changed to ~abc.abstractmethod
  • register is actually a function of generic function. Since we don't get a doc about it., the link is supressed. Create an index entries and anchor of register
  • example is an example function. The link is supressed.

Thanks!

The doc preview of this PR on this library: https://cpython-previews--136424.org.readthedocs.build/en/136424/library/functools.html

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

@bedevere-app bedevere-app bot added awaiting review docs Documentation in the Doc dir skip news labels Jul 8, 2025
@bedevere-app bedevere-app bot mentioned this pull request Jul 8, 2025
Open
@github-project-automation github-project-automation bot moved this to Todo in Docs PRs Jul 8, 2025
serhiy-storchaka
serhiy-storchaka reviewed Jul 8, 2025
View reviewed changes
Copy link
Member

@serhiy-storchaka serhiy-storchaka left a comment

Choose a reason for hiding this comment

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

It would be nice to add index entries and anchors for cache_info, cache_clear and register. You can use :no-typesetting: for this. For example:

.. method:: cache_info()
   :no-typesetting:

Check if this generates a nice index entry.

@rhettinger rhettinger removed their request for review July 8, 2025 20:08
serhiy-storchaka
serhiy-storchaka reviewed Jul 10, 2025
View reviewed changes
Copy link
Member

@serhiy-storchaka serhiy-storchaka left a comment •
edited
Loading

Choose a reason for hiding this comment

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

Thank you for your response.

Please move the definitions immediately above the paragraph that defines the corresponding method. The references can be made inert, e.g. :meth:`!clear_cache` , because it doesn't make sense to add a link to the same paragraph now.

Also, I think that it is better to add a prefix, e.g. .. method:: functools.cache_info(). So the index will contain "cache_info() (functools.lru_cache method)" instead of "cache_info() (in module functools)".

We need to add also an index entry for property.setter, etc, but this is a different issue.

@LamentXU123
Copy link
Contributor Author

LamentXU123 commented Jul 10, 2025 •
edited
Loading

Thank you very much for teaching me this!

I update the prefix and move the definitions to the paragraph that defines the corresponding method, also subpress the referrences.

We need to add also an index entry for property.setter

+1, I think we can add index in later issues.

serhiy-storchaka
serhiy-storchaka reviewed Jul 11, 2025
View reviewed changes
Copy link
Member

@serhiy-storchaka serhiy-storchaka left a comment

Choose a reason for hiding this comment

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

Please move also .. method:: register() and add a prefix to it.

AA-Turner
AA-Turner reviewed Jul 11, 2025
View reviewed changes
LamentXU123 and others added 2 commits July 11, 2025 20:38
@LamentXU123 @AA-Turner
Apply suggestions from code review
a07190e 
Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
@LamentXU123
Update functools.rst
8864e6d
@LamentXU123
Copy link
Contributor Author

Please move also .. method:: register() and add a prefix to it.

Thanks, I will fix it soon.

serhiy-storchaka
serhiy-storchaka reviewed Jul 11, 2025
View reviewed changes
LamentXU123 and others added 2 commits July 11, 2025 21:12
@LamentXU123 @serhiy-storchaka
Apply suggestions from code review
f65d178 
Co-authored-by: Serhiy Storchaka <storchaka@gmail.com>
@LamentXU123
Update functools.rst
f82b0c4
@LamentXU123
Copy link
Contributor Author

Done, Thanks!

serhiy-storchaka
serhiy-storchaka approved these changes Jul 11, 2025
View reviewed changes
Copy link
Member

@serhiy-storchaka serhiy-storchaka left a comment

Choose a reason for hiding this comment

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

LGTM. 👍

Thank you for your contribution @LamentXU123.

@serhiy-storchaka serhiy-storchaka added needs backport to 3.13 bugs and security fixes needs backport to 3.14 bugs and security fixes labels Jul 11, 2025
@serhiy-storchaka serhiy-storchaka merged commit 252e2f7 into python:main Jul 11, 2025
25 checks passed
@github-project-automation github-project-automation bot moved this from Todo to Done in Docs PRs Jul 11, 2025
@miss-islington-app
Copy link

Thanks @LamentXU123 for the PR, and @serhiy-storchaka for merging it 🌮🎉.. I'm working now to backport this PR to: 3.13, 3.14.
🐍🍒⛏🤖

miss-islington pushed a commit to miss-islington/cpython that referenced this pull request Jul 11, 2025
@LamentXU123 @miss-islington
pythongh-101100: Fix sphinx warnings in Doc/library/functools.rst (py…
d429e11 
…thonGH-136424)

Add index entries and anchors for cache_info, cache_clear and register.
(cherry picked from commit 252e2f7)

Co-authored-by: Weilin Du <108666168+LamentXU123@users.noreply.github.com>
@miss-islington-app
Copy link

Sorry, @LamentXU123 and @serhiy-storchaka, I could not cleanly backport this to 3.13 due to a conflict.
Please backport using cherry_picker on command line.

cherry_picker 252e2f710ea376a38c4545dd758e03d331c1eaad 3.13

@bedevere-app
Copy link

bedevere-app bot commented Jul 11, 2025

GH-136552 is a backport of this pull request to the 3.14 branch.

@bedevere-app bedevere-app bot removed the needs backport to 3.14 bugs and security fixes label Jul 11, 2025
serhiy-storchaka pushed a commit to serhiy-storchaka/cpython that referenced this pull request Jul 11, 2025
@LamentXU123 @serhiy-storchaka
[3.13] pythongh-101100: Fix sphinx warnings in Doc/library/functools.…
0790bcd 
…rst (pythonGH-136424)

Add index entries and anchors for cache_info, cache_clear and register.
(cherry picked from commit 252e2f7)

Co-authored-by: Weilin Du <108666168+LamentXU123@users.noreply.github.com>
@bedevere-app
Copy link

bedevere-app bot commented Jul 11, 2025

GH-136554 is a backport of this pull request to the 3.13 branch.

@bedevere-app bedevere-app bot removed the needs backport to 3.13 bugs and security fixes label Jul 11, 2025
serhiy-storchaka pushed a commit that referenced this pull request Jul 11, 2025
@miss-islington @LamentXU123
[3.14] gh-101100: Fix sphinx warnings in Doc/library/functools.rst (G…
ac807cb 
…H-136424) (GH-136552)

Add index entries and anchors for cache_info, cache_clear and register.
(cherry picked from commit 252e2f7)

Co-authored-by: Weilin Du <108666168+LamentXU123@users.noreply.github.com>
serhiy-storchaka added a commit that referenced this pull request Jul 11, 2025
@serhiy-storchaka @LamentXU123
[3.13] gh-101100: Fix sphinx warnings in Doc/library/functools.rst (G…
01710af 
…H-136424) (GH-136554)

Add index entries and anchors for cache_info, cache_clear and register.
(cherry picked from commit 252e2f7)

Co-authored-by: Weilin Du <108666168+LamentXU123@users.noreply.github.com>
Pranjal095 pushed a commit to Pranjal095/cpython that referenced this pull request Jul 12, 2025
@LamentXU123 @Pranjal095
pythongh-101100: Fix sphinx warnings in Doc/library/functools.rst (py…
727ded9 
…thonGH-136424)

Add index entries and anchors for cache_info, cache_clear and register.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@AA-Turner AA-Turner AA-Turner left review comments

@serhiy-storchaka serhiy-storchaka serhiy-storchaka approved these changes

@hugovk hugovk Awaiting requested review from hugovk hugovk is a code owner

Assignees

@serhiy-storchaka serhiy-storchaka

Labels
docs Documentation in the Doc dir skip news
Projects
Docs PRs
Status: Done
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
3 participants
@LamentXU123 @serhiy-storchaka @AA-Turner
pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy