Skip to content
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

Merged
merged 5 commits into from
Feb 25, 2023

Conversation

hugovk
Copy link
Member

@hugovk hugovk commented Feb 21, 2023

Fixes 113 Sphinx warnings found using:

$ cd Doc
$ make clean html SPHINXERRORHANDLING=-n 2>&1 | grep decimal.rst | tee >(wc -l)
/Users/hugo/github/cpython/Doc/library/decimal.rst:42: WARNING: py:const reference target not found: 1.1
/Users/hugo/github/cpython/Doc/library/decimal.rst:42: WARNING: py:const reference target not found: 2.2
/Users/hugo/github/cpython/Doc/library/decimal.rst:42: WARNING: py:const reference target not found: 3.3000000000000003
/Users/hugo/github/cpython/Doc/library/decimal.rst:47: WARNING: py:const reference target not found: 5.5511151231257827e-017
/Users/hugo/github/cpython/Doc/library/decimal.rst:54: WARNING: py:const reference target not found: 2.50
/Users/hugo/github/cpython/Doc/library/decimal.rst:54: WARNING: py:const reference target not found: 1.56
/Users/hugo/github/cpython/Doc/library/decimal.rst:54: WARNING: py:const reference target not found: 1.5600
/Users/hugo/github/cpython/Doc/library/decimal.rst:88: WARNING: py:const reference target not found: Infinity
/Users/hugo/github/cpython/Doc/library/decimal.rst:88: WARNING: py:const reference target not found: -Infinity
/Users/hugo/github/cpython/Doc/library/decimal.rst:88: WARNING: py:const reference target not found: NaN
/Users/hugo/github/cpython/Doc/library/decimal.rst:88: WARNING: py:const reference target not found: -0
/Users/hugo/github/cpython/Doc/library/decimal.rst:88: WARNING: py:const reference target not found: +0
/Users/hugo/github/cpython/Doc/library/decimal.rst:139: WARNING: py:const reference target not found: NaN
/Users/hugo/github/cpython/Doc/library/decimal.rst:139: WARNING: py:const reference target not found: Infinity
/Users/hugo/github/cpython/Doc/library/decimal.rst:139: WARNING: py:const reference target not found: -0
/Users/hugo/github/cpython/Doc/library/decimal.rst:253: WARNING: py:meth reference target not found: quantize
/Users/hugo/github/cpython/Doc/library/decimal.rst:299: WARNING: py:meth reference target not found: clear_flags
/Users/hugo/github/cpython/Doc/library/decimal.rst:312: WARNING: py:const reference target not found: Pi
/Users/hugo/github/cpython/Doc/library/decimal.rst:316: WARNING: py:attr reference target not found: traps
/Users/hugo/github/cpython/Doc/library/decimal.rst:371: WARNING: py:const reference target not found: 0
/Users/hugo/github/cpython/Doc/library/decimal.rst:371: WARNING: py:const reference target not found: 1
/Users/hugo/github/cpython/Doc/library/decimal.rst:387: WARNING: py:const reference target not found: NaN
/Users/hugo/github/cpython/Doc/library/decimal.rst:703: WARNING: py:const reference target not found: NaN
/Users/hugo/github/cpython/Doc/library/decimal.rst:715: WARNING: py:const reference target not found: NaN
/Users/hugo/github/cpython/Doc/library/decimal.rst:746: WARNING: py:const reference target not found: Decimal('0')
/Users/hugo/github/cpython/Doc/library/decimal.rst:746: WARNING: py:const reference target not found: Decimal('0e0')
/Users/hugo/github/cpython/Doc/library/decimal.rst:792: WARNING: py:attr reference target not found: Emax
/Users/hugo/github/cpython/Doc/library/decimal.rst:792: WARNING: py:attr reference target not found: Etiny
/Users/hugo/github/cpython/Doc/library/decimal.rst:832: WARNING: py:const reference target not found: NaN
/Users/hugo/github/cpython/Doc/library/decimal.rst:895: WARNING: py:meth reference target not found: logical_and
/Users/hugo/github/cpython/Doc/library/decimal.rst:895: WARNING: py:meth reference target not found: logical_invert
/Users/hugo/github/cpython/Doc/library/decimal.rst:895: WARNING: py:meth reference target not found: logical_or
/Users/hugo/github/cpython/Doc/library/decimal.rst:895: WARNING: py:meth reference target not found: logical_xor
/Users/hugo/github/cpython/Doc/library/decimal.rst:895: WARNING: py:const reference target not found: 0
/Users/hugo/github/cpython/Doc/library/decimal.rst:895: WARNING: py:const reference target not found: 1
/Users/hugo/github/cpython/Doc/library/decimal.rst:984: WARNING: py:const reference target not found: NaN
/Users/hugo/github/cpython/Doc/library/decimal.rst:984: WARNING: py:const reference target not found: Infinity
/Users/hugo/github/cpython/Doc/library/decimal.rst:1004: WARNING: py:attr reference target not found: prec
/Users/hugo/github/cpython/Doc/library/decimal.rst:1004: WARNING: py:const reference target not found: 28
/Users/hugo/github/cpython/Doc/library/decimal.rst:1004: WARNING: py:attr reference target not found: rounding
/Users/hugo/github/cpython/Doc/library/decimal.rst:1019: WARNING: py:const reference target not found: 1
/Users/hugo/github/cpython/Doc/library/decimal.rst:1028: WARNING: py:const reference target not found: 0
/Users/hugo/github/cpython/Doc/library/decimal.rst:1028: WARNING: py:const reference target not found: 0
/Users/hugo/github/cpython/Doc/library/decimal.rst:1032: WARNING: py:const reference target not found: 0
/Users/hugo/github/cpython/Doc/library/decimal.rst:1032: WARNING: py:const reference target not found: 1
/Users/hugo/github/cpython/Doc/library/decimal.rst:1032: WARNING: py:const reference target not found: 1
/Users/hugo/github/cpython/Doc/library/decimal.rst:1032: WARNING: py:const reference target not found: E
/Users/hugo/github/cpython/Doc/library/decimal.rst:1032: WARNING: py:const reference target not found: e
/Users/hugo/github/cpython/Doc/library/decimal.rst:1032: WARNING: py:const reference target not found: Decimal('6.02e+23')
/Users/hugo/github/cpython/Doc/library/decimal.rst:1036: WARNING: py:const reference target not found: 0
/Users/hugo/github/cpython/Doc/library/decimal.rst:1036: WARNING: py:const reference target not found: 1
/Users/hugo/github/cpython/Doc/library/decimal.rst:1036: WARNING: py:const reference target not found: 1
/Users/hugo/github/cpython/Doc/library/decimal.rst:1036: WARNING: py:const reference target not found: 0
/Users/hugo/github/cpython/Doc/library/decimal.rst:1036: WARNING: py:const reference target not found: 1
/Users/hugo/github/cpython/Doc/library/decimal.rst:1051: WARNING: py:const reference target not found: 1
/Users/hugo/github/cpython/Doc/library/decimal.rst:1054: WARNING: py:meth reference target not found: adjusted
/Users/hugo/github/cpython/Doc/library/decimal.rst:1054: WARNING: py:meth reference target not found: as_tuple
/Users/hugo/github/cpython/Doc/library/decimal.rst:1067: WARNING: py:const reference target not found: 0
/Users/hugo/github/cpython/Doc/library/decimal.rst:1071: WARNING: py:const reference target not found: 0
/Users/hugo/github/cpython/Doc/library/decimal.rst:1487: WARNING: py:const reference target not found: 425000000
/Users/hugo/github/cpython/Doc/library/decimal.rst:1487: WARNING: py:const reference target not found: 999999999999999999
/Users/hugo/github/cpython/Doc/library/decimal.rst:1489: WARNING: py:const reference target not found: 425000000
/Users/hugo/github/cpython/Doc/library/decimal.rst:1489: WARNING: py:const reference target not found: 999999999999999999
/Users/hugo/github/cpython/Doc/library/decimal.rst:1491: WARNING: py:const reference target not found: -425000000
/Users/hugo/github/cpython/Doc/library/decimal.rst:1491: WARNING: py:const reference target not found: -999999999999999999
/Users/hugo/github/cpython/Doc/library/decimal.rst:1493: WARNING: py:const reference target not found: -849999999
/Users/hugo/github/cpython/Doc/library/decimal.rst:1493: WARNING: py:const reference target not found: -1999999999999999997
/Users/hugo/github/cpython/Doc/library/decimal.rst:1517: WARNING: py:const reference target not found: Infinity
/Users/hugo/github/cpython/Doc/library/decimal.rst:1525: WARNING: py:const reference target not found: -Infinity
/Users/hugo/github/cpython/Doc/library/decimal.rst:1572: WARNING: py:attr reference target not found: Emin
/Users/hugo/github/cpython/Doc/library/decimal.rst:1572: WARNING: py:attr reference target not found: Emax
/Users/hugo/github/cpython/Doc/library/decimal.rst:1586: WARNING: py:const reference target not found: Infinity
/Users/hugo/github/cpython/Doc/library/decimal.rst:1586: WARNING: py:const reference target not found: -Infinity
/Users/hugo/github/cpython/Doc/library/decimal.rst:1604: WARNING: py:const reference target not found: NaN
/Users/hugo/github/cpython/Doc/library/decimal.rst:1622: WARNING: py:attr reference target not found: Emax
/Users/hugo/github/cpython/Doc/library/decimal.rst:1622: WARNING: py:const reference target not found: Infinity
/Users/hugo/github/cpython/Doc/library/decimal.rst:1633: WARNING: py:const reference target not found: 5.00
/Users/hugo/github/cpython/Doc/library/decimal.rst:1633: WARNING: py:const reference target not found: 5.0
/Users/hugo/github/cpython/Doc/library/decimal.rst:1641: WARNING: py:attr reference target not found: Emin
/Users/hugo/github/cpython/Doc/library/decimal.rst:1698: WARNING: py:const reference target not found: 0.1
/Users/hugo/github/cpython/Doc/library/decimal.rst:1748: WARNING: py:const reference target not found: NaN
/Users/hugo/github/cpython/Doc/library/decimal.rst:1748: WARNING: py:const reference target not found: sNaN
/Users/hugo/github/cpython/Doc/library/decimal.rst:1748: WARNING: py:const reference target not found: -Infinity
/Users/hugo/github/cpython/Doc/library/decimal.rst:1748: WARNING: py:const reference target not found: Infinity
/Users/hugo/github/cpython/Doc/library/decimal.rst:1748: WARNING: py:const reference target not found: +0
/Users/hugo/github/cpython/Doc/library/decimal.rst:1748: WARNING: py:const reference target not found: -0
/Users/hugo/github/cpython/Doc/library/decimal.rst:1761: WARNING: py:const reference target not found: NaN
/Users/hugo/github/cpython/Doc/library/decimal.rst:1761: WARNING: py:const reference target not found: NaN
/Users/hugo/github/cpython/Doc/library/decimal.rst:1761: WARNING: py:const reference target not found: NaN
/Users/hugo/github/cpython/Doc/library/decimal.rst:1761: WARNING: py:const reference target not found: NaN
/Users/hugo/github/cpython/Doc/library/decimal.rst:1769: WARNING: py:const reference target not found: sNaN
/Users/hugo/github/cpython/Doc/library/decimal.rst:1773: WARNING: py:const reference target not found: NaN
/Users/hugo/github/cpython/Doc/library/decimal.rst:1773: WARNING: py:const reference target not found: NaN
/Users/hugo/github/cpython/Doc/library/decimal.rst:1773: WARNING: py:const reference target not found: NaN
/Users/hugo/github/cpython/Doc/library/decimal.rst:1773: WARNING: py:const reference target not found: NaN
/Users/hugo/github/cpython/Doc/library/decimal.rst:1773: WARNING: py:meth reference target not found: compare
/Users/hugo/github/cpython/Doc/library/decimal.rst:1773: WARNING: py:meth reference target not found: compare-signal
/Users/hugo/github/cpython/Doc/library/decimal.rst:2016: WARNING: py:meth reference target not found: quantize
/Users/hugo/github/cpython/Doc/library/decimal.rst:2037: WARNING: py:meth reference target not found: quantize
/Users/hugo/github/cpython/Doc/library/decimal.rst:2055: WARNING: py:meth reference target not found: quantize
/Users/hugo/github/cpython/Doc/library/decimal.rst:2069: WARNING: py:const reference target not found: 200
/Users/hugo/github/cpython/Doc/library/decimal.rst:2069: WARNING: py:const reference target not found: 200.000
/Users/hugo/github/cpython/Doc/library/decimal.rst:2069: WARNING: py:const reference target not found: 2E2
/Users/hugo/github/cpython/Doc/library/decimal.rst:2069: WARNING: py:const reference target not found: 02E+4
/Users/hugo/github/cpython/Doc/library/decimal.rst:2074: WARNING: py:meth reference target not found: normalize
/Users/hugo/github/cpython/Doc/library/decimal.rst:2084: WARNING: py:const reference target not found: 5.0E+3
/Users/hugo/github/cpython/Doc/library/decimal.rst:2084: WARNING: py:const reference target not found: 5000
/Users/hugo/github/cpython/Doc/library/decimal.rst:2162: WARNING: py:attr reference target not found: Emin
/Users/hugo/github/cpython/Doc/library/decimal.rst:2162: WARNING: py:attr reference target not found: Emax
/Users/hugo/github/cpython/Doc/library/decimal.rst:2162: WARNING: py:attr reference target not found: clamp
/Users/hugo/github/cpython/Doc/library/decimal.rst:2162: WARNING: py:attr reference target not found: prec
/Users/hugo/github/cpython/Doc/library/decimal.rst:2166: WARNING: py:attr reference target not found: prec
/Users/hugo/github/cpython/Doc/library/decimal.rst:2183: WARNING: py:attr reference target not found: prec
     113

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

Copy link
Member

@CAM-Gerlach CAM-Gerlach left a 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 of meth:`~decimal.Decimal.quantize`
  • Fix a couple other issues with the changes

Doc/library/decimal.rst Outdated Show resolved Hide resolved
Doc/library/decimal.rst Outdated Show resolved Hide resolved
Doc/library/decimal.rst Outdated Show resolved Hide resolved
Doc/library/decimal.rst Outdated Show resolved Hide resolved
Doc/library/decimal.rst Outdated Show resolved Hide resolved
Doc/library/decimal.rst Outdated Show resolved Hide resolved
Doc/library/decimal.rst Outdated Show resolved Hide resolved
Doc/library/decimal.rst Outdated Show resolved Hide resolved
Doc/library/decimal.rst Outdated Show resolved Hide resolved
Doc/library/decimal.rst Outdated Show resolved Hide resolved
hugovk and others added 2 commits February 22, 2023 17:04
Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>
@hugovk hugovk force-pushed the docs-fix-decimal-warnings branch from 5616f0c to 498e6f8 Compare February 22, 2023 15:31
@hugovk
Copy link
Member Author

hugovk commented Feb 22, 2023

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

Doc/library/decimal.rst Outdated Show resolved Hide resolved
Doc/library/decimal.rst Outdated Show resolved Hide resolved
Copy link
Member

@mdickinson mdickinson 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 doing this!

Copy link
Member

@CAM-Gerlach CAM-Gerlach left a 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.

Doc/library/decimal.rst Outdated Show resolved Hide resolved
Doc/library/decimal.rst Outdated Show resolved Hide resolved
Doc/library/decimal.rst Outdated Show resolved Hide resolved
Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>
@hugovk
Copy link
Member Author

hugovk commented Feb 23, 2023

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

Copy link
Member

@CAM-Gerlach CAM-Gerlach left a comment

Choose a reason for hiding this comment

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

LGTM, thanks @hugovk !

@hugovk hugovk merged commit b7c1126 into python:main Feb 25, 2023
@miss-islington
Copy link
Contributor

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

@miss-islington
Copy link
Contributor

Sorry @hugovk, I had trouble checking out the 3.11 backport branch.
Please retry by removing and re-adding the "needs backport to 3.11" label.
Alternatively, you can backport using cherry_picker on the command line.
cherry_picker b7c11264476ccc11e4bdf4bd3c3664ccd1b7c5f9 3.11

miss-islington pushed a commit to miss-islington/cpython that referenced this pull request Feb 25, 2023
…2125)

(cherry picked from commit b7c1126)

Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com>
Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>
@bedevere-bot
Copy link

GH-102237 is a backport of this pull request to the 3.10 branch.

@bedevere-bot bedevere-bot removed the needs backport to 3.10 only security fixes label Feb 25, 2023
@AlexWaygood AlexWaygood added needs backport to 3.11 only security fixes and removed needs backport to 3.11 only security fixes labels Feb 25, 2023
@miss-islington
Copy link
Contributor

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

@bedevere-bot
Copy link

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

miss-islington pushed a commit to miss-islington/cpython that referenced this pull request Feb 25, 2023
…2125)

(cherry picked from commit b7c1126)

Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com>
Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>
@bedevere-bot bedevere-bot removed the needs backport to 3.11 only security fixes label Feb 25, 2023
@hugovk hugovk deleted the docs-fix-decimal-warnings branch February 25, 2023 09:50
miss-islington added a commit that referenced this pull request Feb 25, 2023
(cherry picked from commit b7c1126)

Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com>
Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>
miss-islington added a commit that referenced this pull request Feb 25, 2023
(cherry picked from commit b7c1126)

Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com>
Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
docs Documentation in the Doc dir skip news
Projects
None yet
Development

Successfully merging this pull request may close these issues.

6 participants