gh-101100: Fix Sphinx warnings in decimal module

[hugovk]

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

• Issue: Fix all Sphinx reference warnings in the documentation #101100

[CAM-Gerlach]

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

[hugovk]

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

[mdickinson]

LGTM. Thank you for doing this!

[CAM-Gerlach]

Seems like I missed a couple spots, sorry.

[hugovk]

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

[CAM-Gerlach]

LGTM, thanks @hugovk !

[miss-islington]

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

[miss-islington]

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

[bedevere-bot]

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

[miss-islington]

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

[bedevere-bot]

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