-
-
Notifications
You must be signed in to change notification settings - Fork 30.9k
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 our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
gh-101100: Fix Sphinx warnings in decimal
module
#102125
Conversation
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thanks! IMO, I would just strip the extra :const:
role and just use a regular literal, since its still changing the same lines, it's shorter, less noisy and easier to read than adding a !
and :const:
is unambiguously the semantically wrong role here. It also avoids a bunch of extra line diffs on the table width, so it's actually a net win from a diff perspective.
Some other changes:
- Make several references point to their actual target instead of just silencing them
- Don't silence instances that are legitimate warnings of existing public attributes that are mentioned and used in examples but not formally documented (e.g.
Context.prec
,Context.Emax
/Emin
, etc. - Use less verbose and more conventional form omitting current module (e.g.
meth:`~Decimal.quantize`
instead ofmeth:`~decimal.Decimal.quantize`
- Fix a couple other issues with the changes
Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>
5616f0c
to
498e6f8
Compare
Thanks for the review! Yep, I've replaced those const roles with regular literals. The warnings: $ make html SPHINXERRORHANDLING=-n 2>&1 | grep decimal.rst | tee >(wc -l)
/Users/hugo/github/cpython/Doc/library/decimal.rst:316: WARNING: py:attr reference target not found: Context.traps
/Users/hugo/github/cpython/Doc/library/decimal.rst:22: WARNING: py:attr reference target not found: Emax
/Users/hugo/github/cpython/Doc/library/decimal.rst:22: WARNING: py:meth reference target not found: Etiny
/Users/hugo/github/cpython/Doc/library/decimal.rst:13: WARNING: py:attr reference target not found: Context.prec
/Users/hugo/github/cpython/Doc/library/decimal.rst:13: WARNING: py:attr reference target not found: Context.rounding
/Users/hugo/github/cpython/Doc/library/decimal.rst:3: WARNING: py:attr reference target not found: Context.Emin
/Users/hugo/github/cpython/Doc/library/decimal.rst:3: WARNING: py:attr reference target not found: Context.Emax
/Users/hugo/github/cpython/Doc/library/decimal.rst:3: WARNING: py:attr reference target not found: Emax
/Users/hugo/github/cpython/Doc/library/decimal.rst:1: WARNING: py:attr reference target not found: Context.Emin
/Users/hugo/github/cpython/Doc/library/decimal.rst:2162: WARNING: py:attr reference target not found: Context.Emin
/Users/hugo/github/cpython/Doc/library/decimal.rst:2162: WARNING: py:attr reference target not found: Context.Emax
/Users/hugo/github/cpython/Doc/library/decimal.rst:2162: WARNING: py:attr reference target not found: Context.clamp
/Users/hugo/github/cpython/Doc/library/decimal.rst:2162: WARNING: py:attr reference target not found: Context.prec
/Users/hugo/github/cpython/Doc/library/decimal.rst:2166: WARNING: py:attr reference target not found: Context.prec
/Users/hugo/github/cpython/Doc/library/decimal.rst:2183: WARNING: py:attr reference target not found: Context.prec
15 |
There was a problem hiding this 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 doing this!
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Seems like I missed a couple spots, sorry.
Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>
Thanks both! Warnings now: $ make clean html SPHINXERRORHANDLING=-n 2>&1 | grep decimal.rst | tee >(wc -l)
/Users/hugo/github/cpython/Doc/library/decimal.rst:316: WARNING: py:attr reference target not found: Context.traps
/Users/hugo/github/cpython/Doc/library/decimal.rst:792: WARNING: py:attr reference target not found: Context.Emax
/Users/hugo/github/cpython/Doc/library/decimal.rst:1004: WARNING: py:attr reference target not found: Context.prec
/Users/hugo/github/cpython/Doc/library/decimal.rst:1004: WARNING: py:attr reference target not found: Context.rounding
/Users/hugo/github/cpython/Doc/library/decimal.rst:1036: WARNING: py:attr reference target not found: Context.Emax
/Users/hugo/github/cpython/Doc/library/decimal.rst:1572: WARNING: py:attr reference target not found: Context.Emin
/Users/hugo/github/cpython/Doc/library/decimal.rst:1572: WARNING: py:attr reference target not found: Context.Emax
/Users/hugo/github/cpython/Doc/library/decimal.rst:1622: WARNING: py:attr reference target not found: Context.Emax
/Users/hugo/github/cpython/Doc/library/decimal.rst:1641: WARNING: py:attr reference target not found: Context.Emin
/Users/hugo/github/cpython/Doc/library/decimal.rst:2162: WARNING: py:attr reference target not found: Context.Emin
/Users/hugo/github/cpython/Doc/library/decimal.rst:2162: WARNING: py:attr reference target not found: Context.Emax
/Users/hugo/github/cpython/Doc/library/decimal.rst:2162: WARNING: py:attr reference target not found: Context.clamp
/Users/hugo/github/cpython/Doc/library/decimal.rst:2162: WARNING: py:attr reference target not found: Context.prec
/Users/hugo/github/cpython/Doc/library/decimal.rst:2166: WARNING: py:attr reference target not found: Context.prec
/Users/hugo/github/cpython/Doc/library/decimal.rst:2183: WARNING: py:attr reference target not found: Context.prec
15 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
LGTM, thanks @hugovk !
Thanks @hugovk for the PR 🌮🎉.. I'm working now to backport this PR to: 3.10, 3.11. |
Sorry @hugovk, I had trouble checking out the |
GH-102237 is a backport of this pull request to the 3.10 branch. |
Thanks @hugovk for the PR 🌮🎉.. I'm working now to backport this PR to: 3.11. |
GH-102238 is a backport of this pull request to the 3.11 branch. |
Fixes 113 Sphinx warnings found using:
I've mostly fixed these by adding
!
inside the directive, telling Sphinx not to perform a lookup.Some of these could be replaced with literals, like
:const:`!1.1`
->1.1
, and I'm happy to make those changes, but I generally went for a minimal diff here.I expanded method references, for example:
:meth:`quantize`
->:meth:`~decimal.Decimal.quantize`
Before
https://docs.python.org/3.12/library/decimal.html
After
https://deploy-preview-102125--python-cpython-preview.netlify.app/library/decimal.html