Fix all Sphinx reference warnings in the documentation

[JulienPalard]

Documentation

Running sphinx-build in nit-picky mode, like:

sphinx-build -n . build/html/

or:

make html SPHINXERRORHANDLING=-n

gives tons warnings. ~8k of them at the time of writing.

Most of them are innocent, like using :const: while referring to a constant defined in another file, or using :meth:`__init__` to speak about the concept of an init method.

The fall in several cases:

• The target is not documented at all, then document it, like in 664aa94
• There's a typo, then fix it.
• We're mentionning something that does not exists (or no longer exists), then rewrite.
• Innocent usage of rst markers without the intention of linking to something, then ???

I don't have statistics (yet) on the distribution for the 4 previous cases.

For the innocent usages of rst markers, there's two fixes:

• Drop the role, :const:`IGNORECASE` becomes ``IGNORECASE``. We loose a bit of information in the rst file, I'm not fully convinced.
• Make it point to something existing, :const:`IGNORECASE` becomes :const:`re.IGNORECASE`, or even :const:`~re.IGNORECASE` to keep the same output. It means more typing, and more links in the HTML output which are not all usefull.

My question is: should we try to fix all warnings so we can easily spot typos at build time?

I tried to see if some typo would have been avoided by the nit-picky mode by reading a few pages of WARNINGS and found just one: read1 instead of read in bz2.rst.

Linked PRs

• gh-101100: Fix sphinx warnings in enum module #101122
• [3.11] gh-101100: [Enum] Fix sphinx warnings in docs (GH-101122) #101173
• gh-101100: Fix Sphinx warnings in decimal module #102125
• [3.10] gh-101100: Fix Sphinx warnings in decimal module (GH-102125) #102237
• [3.11] gh-101100: Fix Sphinx warnings in decimal module (GH-102125) #102238
• gh-101100: Fix sphinx warnings in typing module #102260
• [3.11] gh-101100: Fix sphinx warnings in typing module docs (GH-102260) #102262
• [3.10] gh-101100: Fix sphinx warnings in typing module docs (GH-102260) #102263
• gh-101100: Fix sphinx warnings in types module #102274
• [3.11] gh-101100: Fix sphinx warnings in types module (GH-102274) #102291
• [3.10] gh-101100: Fix sphinx warnings in types module (GH-102274) #102292
• gh-101100: Fix Sphinx warnings in turtle module #102340
• gh-101100: Test docs in nit-picky mode #102513
• gh-101100: Fix sphinx warnings in zipapp and zipfile modules #102526
• [3.10] gh-101100: Fix sphinx warnings in zipapp and zipfile modules (GH-102526) #102529
• [3.11] gh-101100: Fix sphinx warnings in zipapp and zipfile modules (GH-102526) #102530
• gh-101100: [docs] Fix Sphinx warnings in dis module #102597
• [3.10] gh-101100: Fix Sphinx warnings in turtle module (GH-102340) #102638
• [3.11] gh-101100: Fix Sphinx warnings in turtle module (GH-102340) #102639
• gh-101100: Documenting --prefix and --exec-prefix. #102695
• [3.11] gh-101100: Documenting --prefix and --exec-prefix. (GH-102695) #102727
• [3.10] gh-101100: Documenting --prefix and --exec-prefix. (GH-102695) #102728
• [3.11] gh-101100: Document PyObject_ClearWeakRefs, gzip's name, and asyncio.iscoroutine #103001
• [3.10] gh-101100: Document PyObject_ClearWeakRefs and gzip's name #103002
• gh-101100: Test only Doc/ files in nit-picky mode #103019
• gh-101100: Fix Sphinx warning in gc.rst and refactor docs clean list #103116
• gh-101100: Expand list of clean docs #103135
• gh-101100: Use list of 'dirty' docs, with warnings, instead of a clean list #103191
• gh-101100: Fix Sphinx warnings in argparse module #103289
• gh-101100: Fix Sphinx warnings in curses and curses.ascii modules #103457
• gh-101100: Fix broken reference __format__ in string.rst #103531
• [3.11] gh-101100: Fix Sphinx warnings in argparse module (#103289) #103803
• gh-101100: Add reference doc for __post_init__ #103818
• [3.11] gh-101100: Fix Sphinx warnings in curses and curses.ascii modules (GH-103457) #104124
• gh-101100: Fix reference to parse_args in optparse.rst #105265
• gh-101100: Fix reference to asynchronous methods #106172
• [3.12] gh-101100: Fix reference to asynchronous methods (GH-106172) #106191
• [3.11] gh-101100: Fix reference to asynchronous methods (GH-106172) #106192
• [3.12] gh-101100: Fix reference to parse_args in optparse.rst (GH-105265) #106204
• [3.11] gh-101100: Fix reference to parse_args in optparse.rst (GH-105265) #106205
• gh-101100: Fix incorrect roles of C-const in PyUnicode_RichCompare #106220
• gh-101100: Docs: Fix references to several numeric dunders #106278
• [3.12] gh-101100: Docs: Fix references to several numeric dunders (GH-106278) #106281
• [3.11] gh-101100: Docs: Fix references to several numeric dunders (GH-106278) #106282
• gh-101100: Fix incorrect roles of PyTrace_* #106299
• gh-101100: Docs: Check Sphinx warnings and fail if improved #106460
• gh-101100: Fix some broken sphinx references #107095
• [3.12] gh-101100: Fix some broken sphinx references (GH-107095) #107103
• [3.11] gh-101100: Fix some broken sphinx references (GH-107095). #107120
• gh-101100: Sphinx warnings: pick the low hanging fruits #107386
• [3.11] gh-101100: Sphinx warnings: pick the low hanging fruits (GH-107386) #107418
• [3.12] gh-101100: Sphinx warnings: pick the low hanging fruits (GH-107386) #107419
• gh-101100: Fix references to URLError and HTTPError in howto/urllib2.rst #107966
• gh-101100: Only show GitHub check annotations on changed doc paragraphs #108065
• [3.12] gh-101100: Only show GitHub check annotations on changed doc paragraphs (GH-108065) #108127
• gh-101100: Fix Sphinx warnings in the Logging Cookbook #108678
• [3.12] gh-101100: Fix Sphinx warnings in the Logging Cookbook (GH-108678) #108680
• [3.11] gh-101100: Fix Sphinx warnings in the Logging Cookbook (GH-108678) #108681
• gh-101100: Fix sphinx warnings in threading.rst #108684
• [3.12] gh-101100: Fix sphinx warnings in threading.rst (GH-108684) #108707
• [3.11] gh-101100: Fix sphinx warnings in threading.rst (GH-108684) #108708
• gh-101100: Fix sphinx warnings in tutorial/classes.rst #108746
• gh-101100: Fix sphinx warnings in tutorial/appendix.rst #108750
• [3.11] gh-101100: Fix sphinx warnings in tutorial/classes.rst (GH-108746) #108755
• [3.12] gh-101100: Fix sphinx warnings in tutorial/classes.rst (GH-108746) #108756
• [3.11] gh-101100: Fix sphinx warnings in tutorial/appendix.rst (GH-108750) #108757
• [3.12] gh-101100: Fix sphinx warnings in tutorial/appendix.rst (GH-108750) #108759
• gh-101100: Fix sphinx warnings in uuid.rst #108805
• [3.12] gh-101100: Fix sphinx warnings in uuid.rst (GH-108805) #108807
• [3.11] gh-101100: Fix sphinx warnings in uuid.rst (GH-108805) #108808
• gh-101100: Fix sphinx warnings in unittest.mock-examples.rst #108810
• [3.11] gh-101100: Fix sphinx warnings in unittest.mock-examples.rst (GH-108810) #108812
• [3.12] gh-101100: Fix sphinx warnings in unittest.mock-examples.rst (GH-108810) #108813
• gh-101100: Fix sphinx warnings in turtle.rst #109394
• [3.12] gh-101100: Fix sphinx warnings in turtle.rst (GH-109394) #109416
• [3.11] gh-101100: Fix sphinx warnings in turtle.rst (GH-109394) #109417
• gh-101100: Fix Sphinx warnings in tutorial/controlflow.rst #109424
• gh-101100: Fix sphinx warnings in Doc/library/xml.etree.elementtree.rst #109799
• [3.12] gh-101100: Fix sphinx warnings in Doc/library/xml.etree.elementtree.rst (GH-109799) #109800
• [3.11] gh-101100: Fix sphinx warnings in Doc/library/xml.etree.elementtree.rst (GH-109799) #109801
• gh-101100: Fix sphinx warnings in Doc/library/__future__.rst #109814
• gh-101100: Fix Sphinx warnings in Doc/library/weakref.rst #109881
• [3.11] gh-101100: Fix Sphinx warnings in Doc/library/weakref.rst (GH-109881) #109883
• [3.12] gh-101100: Fix Sphinx warnings in Doc/library/weakref.rst (GH-109881) #109884
• gh-101100: Fix Sphinx warnings in Doc/using/configure.rst #109931
• [3.12] gh-101100: Fix Sphinx warnings in Doc/using/configure.rst (GH-109931) #109937
• [3.11] gh-101100: Fix Sphinx warnings in Doc/using/configure.rst (GH-109931) #109938
• gh-101100: Fix sphinx warnings in library/devmode.rst #109963
• [3.12] gh-101100: Fix sphinx warnings in library/devmode.rst (GH-109963) #109966
• [3.11] gh-101100: Fix sphinx warnings in library/devmode.rst (GH-109963) #109967
• gh-101100: Fix sphinx warnings in library/difflib.rst #110074
• [3.12] gh-101100: Fix sphinx warnings in library/difflib.rst (GH-110074) #110081
• [3.11] gh-101100: Fix sphinx warnings in library/difflib.rst (GH-110074) #110082
• [3.12] gh-101100: Fix Sphinx warnings in tutorial/controlflow.rst (GH-109424) #110084
• [3.11] gh-101100: Fix Sphinx warnings in tutorial/controlflow.rst (GH-109424) #110085
• [3.12] gh-101100: Fix references to URLError and HTTPError in howto/urllib2.rst (GH-107966) #110086
• [3.11] gh-101100: Fix references to URLError and HTTPError in howto/urllib2.rst (GH-107966) #110087
• GH-101100: Fix reference warnings for __enter__ and __exit__ #110112
• GH-101100: Fix reference warnings for namedtuple #110113
• GH-101100: Fix reference warnings for socket methods #110114
• GH-101100: Fix reference warnings for gettext #110115
• GH-101100: Fix reference warnings for __getitem__ #110118
• [3.12] GH-101100: Fix reference warnings for namedtuple (GH-110113) #110135
• [3.11] GH-101100: Fix reference warnings for namedtuple (GH-110113) #110136
• [3.12] GH-101100: Fix reference warnings for gettext (GH-110115) #110140
• [3.11] GH-101100: Fix reference warnings for gettext (GH-110115) #110141
• gh-101100: Fix sphinx warnings in library/site.rst #110144
• [3.11] gh-101100: Fix sphinx warnings in library/site.rst (GH-110144) #110185
• [3.12] gh-101100: Fix sphinx warnings in library/site.rst (GH-110144) #110187
• gh-101100: Fix sphinx warnings in library/socketserver.rst #110207
• gh-101100: Fix sphinx warnings in library/getpass.rst #110461
• [3.12] gh-101100: Fix sphinx warnings in library/socketserver.rst (GH-110207) #110623
• [3.11] gh-101100: Fix sphinx warnings in library/socketserver.rst (GH-110207) #110624
• gh-101100: Fix sphinx warnings in usage/cmdline.rst #110841
• [3.12] gh-101100: Fix sphinx warnings in usage/cmdline.rst (GH-110841) #110855
• [3.11] gh-101100: Fix sphinx warnings in usage/cmdline.rst (GH-110841) #110856
• gh-101100: Fix sphinx warnings in library/time.rst #110862
• [3.12] gh-101100: Fix sphinx warnings in library/time.rst (GH-110862) #110877
• [3.11] gh-101100: Fix sphinx warnings in library/time.rst (GH-110862) #110878
• gh-101100: Fix sphinx warnings in library/codecs.rst #110979
• [3.12] gh-101100: Fix sphinx warnings in library/codecs.rst (GH-110979) #111070
• [3.11] gh-101100: Fix sphinx warnings in library/codecs.rst (GH-110979) #111071
• [3.11] gh-101100: Fix sphinx warnings in library/getpass.rst (GH-110461) #111072
• [3.12] GH-101100: Fix reference warnings for __getitem__ (GH-110118) #111073
• [3.11] GH-101100: Fix reference warnings for __getitem__ (GH-110118) #111074
• [3.12] GH-101100: Fix reference warnings for __enter__ and __exit__ (GH-110112) #111075
• [3.11] GH-101100: Fix reference warnings for __enter__ and __exit__ (GH-110112) #111076
• gh-101100: Fix Sphinx warnings in library/tty.rst #111079
• [3.12] gh-101100: Fix sphinx warnings in library/getpass.rst (GH-110461) #111080
• [3.12] gh-101100: Fix Sphinx warnings in library/tty.rst (GH-111079) #111097
• [3.11] gh-101100: Fix Sphinx warnings in library/tty.rst (GH-111079) #111098
• gh-101100: Fix Sphinx warnings for fileno #111118
• gh-101100: Fix Sphinx warning in tutorial/introduction.rst #111173
• [3.12] gh-101100: Fix Sphinx warning in tutorial/introduction.rst (GH-111173) #111175
• [3.11] gh-101100: Fix Sphinx warning in tutorial/introduction.rst (GH-111173) #111176
• gh-101100: Fix sphinx warnings in library/asyncio-dev.rst #111179
• [3.12] gh-101100: Fix sphinx warnings in library/asyncio-dev.rst (GH-111179) #111185
• [3.11] gh-101100: Fix sphinx warnings in library/asyncio-dev.rst (GH-111179) #111186
• gh-101100: Fix sphinx warnings in library/asyncio-eventloop.rst #111222
• [3.12] gh-101100: Fix Sphinx warnings for fileno (GH-111118) #111226
• [3.11] gh-101100: Fix Sphinx warnings for fileno (GH-111118) #111227
• [3.12] gh-101100: Fix sphinx warnings in library/asyncio-eventloop.rst (GH-111222) #111469
• [3.11] gh-101100: Fix sphinx warnings in library/asyncio-eventloop.rst (GH-111222) #111470
• gh-101100: Fix Sphinx warnings in whatsnew/2.0.rst #112351
• gh-101100: Fix Sphinx warnings in whatsnew/2.1.rst #112357
• gh-101100: Fix Sphinx warnings in whatsnew/2.2.rst #112366
• gh-101100: Fix Sphinx warnings in whatsnew/2.3.rst #112373
• gh-101100: Define test.regrtest module to fix references #112381
• gh-101100: Define _tkinter module to fix references #112382
• [3.12] gh-101100: Define test.regrtest module to fix references (GH-112381) #112390
• [3.11] gh-101100: Define test.regrtest module to fix references (GH-112381) #112391
• [3.12] gh-101100: Define _tkinter module to fix references (GH-112382) #112392
• [3.11] gh-101100: Define _tkinter module to fix references (GH-112382) #112393
• gh-101100 : Fix Sphinx warnings in library/doctest.rst #112399
• [3.12] gh-101100 : Fix Sphinx warnings in library/doctest.rst (GH-112399) #112402
• [3.11] gh-101100 : Fix Sphinx warnings in library/doctest.rst (GH-112399) #112404
• gh-101100: Fix Sphinx reference warnings #112416
• [3.12] gh-101100: Fix Sphinx reference warnings (GH-112416) #112420
• [3.11] gh-101100: Fix Sphinx reference warnings (GH-112416) #112422
• [3.12] GH-101100: Fix reference warnings for socket methods (GH-110114) #112455
• [3.11] GH-101100: Fix reference warnings for socket methods (GH-110114) #112456
• gh-101100: Fix most Sphinx nitpicks in inspect.rst #112662
• [3.12] gh-101100: Fix most Sphinx nitpicks in inspect.rst (GH-112662) #112666
• [3.11] gh-101100: Fix most Sphinx nitpicks in inspect.rst (GH-112662) #112667
• gh-101100: Fix Sphinx warning in library/gettext.rst #112668
• gh-101100: Fix Sphinx nitpicks in library/functions.rst #112669
• [3.11] gh-101100: Fix Sphinx warning in library/gettext.rst (GH-112668) #112673
• [3.12] gh-101100: Fix Sphinx warning in library/gettext.rst (GH-112668) #112674
• [3.12] gh-101100: Fix Sphinx nitpicks in library/functions.rst (GH-112669) #112697
• [3.11] gh-101100: Fix Sphinx nitpicks in library/functions.rst (GH-112669) #112698
• [3.11] gh-101100: Fix sphinx warnings in Doc/library/__future__.rst (GH-109814) #112701
• [3.12] gh-101100: Fix sphinx warnings in Doc/library/__future__.rst (#109814) #112702
• gh-101100: Fix Sphinx nitpicks in library/abc.rst #112703
• [3.11] gh-101100: Fix Sphinx nitpicks in library/abc.rst (GH-112703) #112704
• [3.12] gh-101100: Fix Sphinx nitpicks in library/abc.rst (#112703) #112705
• gh-101100: Properly document frame object attributes #112735
• gh-101100: Fix many easily solvable Sphinx nitpicks in the datamodel docs #112737
• [3.12] gh-101100: Fix many easily solvable Sphinx nitpicks in the datamodel docs (GH-112737) #112748
• [3.11] gh-101100: Fix many easily solvable Sphinx nitpicks in the datamodel docs (GH-112737) #112749
• gh-101100: Fix most Sphinx nitpicks in the glossary and stdtypes.rst #112757
• [3.12] gh-101100: Properly document frame object attributes (GH-112735) #112772
• [3.11] gh-101100: Properly document frame object attributes (#112735) #112775
• gh-101100: Improve documentation of code object attributes #112781
• [3.12] gh-101100: Fix most Sphinx nitpicks in the glossary and stdtypes.rst (GH-112757) #112789
• [3.11] gh-101100: Fix most Sphinx nitpicks in the glossary and stdtypes.rst (GH-112757) #112790
• gh-101100: Fix Sphinx nitpicks in library/reprlib.rst #112811
• [3.12] gh-101100: Fix Sphinx nitpicks in library/reprlib.rst (GH-112811) #112813
• [3.11] gh-101100: Fix Sphinx nitpicks in library/reprlib.rst (#112811) #112815
• [3.12] gh-101100: Improve documentation of code object attributes (#112781) #112816
• [3.11] gh-101100: Improve documentation of code object attributes (#112781) #112817
• gh-101100: Improve documentation for attributes on instance methods #112832
• gh-101100: Silence Sphinx warnings when ntpath or posixpath are referenced #112833
• gh-101100: Fix Sphinx nitpicks in library/shelve.rst #112836
• [3.12] gh-101100: Silence Sphinx warnings when ntpath or posixpath are referenced (#112833) #112857
• [3.11] gh-101100: Silence Sphinx warnings when ntpath or posixpath are referenced (#112833) #112858
• [3.12] gh-101100: Fix Sphinx nitpicks in library/shelve.rst (GH-112836) #112868
• [3.11] gh-101100: Fix Sphinx nitpicks in library/shelve.rst (GH-112836) #112869
• gh-101100: Fix Sphinx nits in library/contextlib.rst #112870
• [3.12] gh-101100: Improve documentation for attributes on instance methods (GH-112832) #112872
• [3.11] gh-101100: Improve documentation for attributes on instance methods (GH-112832) #112873
• [3.11] gh-101100: Fix Sphinx nits in library/contextlib.rst (#112870) #112874
• [3.12] gh-101100: Fix Sphinx nits in library/contextlib.rst (#112870) #112875
• gh-101100: Improve documentation of TracebackType attributes #112884
• gh-101100: Fix Sphinx nitpicks in library/tempfile.rst #112886
• gh-101100: Fix Sphinx warning in library/http.cookies.rst #112908
• [3.12] gh-101100: Fix Sphinx nitpicks in library/tempfile.rst (#112886) #112910
• [3.12] gh-101100: Improve documentation of TracebackType attributes (GH-112884) #112911
• [3.11] gh-101100: Improve documentation of TracebackType attributes (GH-112884) #112912
• [3.11] gh-101100: Fix Sphinx nitpicks in library/tempfile.rst (#112886) #112913
• [3.12] gh-101100: Fix Sphinx warning in library/http.cookies.rst (GH-112908) #112929
• [3.11] gh-101100: Fix Sphinx warning in library/http.cookies.rst (GH-112908) #112930
• gh-101100: Improve documentation on function attributes #112933
• [3.12] gh-101100: Improve documentation on function attributes (GH-112933) #112974
• gh-101100: Fix Sphinx warnings in library/random.rst #112981
• gh-101100: Further improve docs on function attributes #113001
• [3.11] gh-101100: Improve documentation on function attributes (#112933) #113003
• gh-101100: Fix Sphinx warning in references with asterisks #113029
• [3.12] gh-101100: Further improve docs on function attributes (GH-113001) #113030
• [3.11] gh-101100: Further improve docs on function attributes (#113001) #113031
• [3.12] gh-101100: Fix Sphinx warning in references with asterisks (GH-113029) #113043
• [3.11] gh-101100: Fix Sphinx warning in references with asterisks (GH-113029) #113044
• gh-101100: Improve docs on exception attributes #113057
• [3.12] gh-101100: Improve docs on exception attributes (GH-113057) #113061
• [3.11] gh-101100: Improve docs on exception attributes (GH-113057) #113062
• gh-101100: Fix Sphinx nitpicks in library/traceback.rst #113106
• gh-101100: Fix Sphinx nitpicks in library/inspect.rst and reference/simple_stmts.rst #113107
• [3.12] gh-101100: Fix Sphinx nitpicks in library/inspect.rst and reference/simple_stmts.rst (GH-113107) #113109
• [3.11] gh-101100: Fix Sphinx nitpicks in library/inspect.rst and reference/simple_stmts.rst (GH-113107) #113110
• [3.12] gh-101100: Fix Sphinx nitpicks in library/traceback.rst (GH-113106) #113111
• [3.11] gh-101100: Fix Sphinx nitpicks in library/traceback.rst (GH-113106) #113112
• gh-101100: Fix Sphinx nitpicks in library/collections.abc.rst #113116
• gh-101100: Cleanup mailbox docs #113124
• gh-101100: Fix Sphinx nitpicks in library/rlcompleter.rst #113125
• [3.12] gh-101100: Fix Sphinx nitpicks in library/collections.abc.rst (GH-113116) #113136
• [3.11] gh-101100: Fix Sphinx nitpicks in library/collections.abc.rst (GH-113116) #113137
• [3.12] gh-101100: Fix Sphinx warnings in whatsnew/2.3.rst (GH-112373) #113142
• [3.11] gh-101100: Fix Sphinx warnings in whatsnew/2.3.rst (GH-112373) #113143
• [3.12] gh-101100: Cleanup mailbox docs (GH-113124) #113144
• [3.11] gh-101100: Cleanup mailbox docs (GH-113124) #113145
• [3.12] gh-101100: Fix Sphinx nitpicks in library/rlcompleter.rst (GH-113125) #113158
• [3.11] gh-101100: Fix Sphinx nitpicks in library/rlcompleter.rst (GH-113125) #113159
• gh-101100: Fix Sphinx nitpicks in library/numbers.rst #113162
• gh-101100: Fix various Sphinx warnings for dunder references in the library/ directory #113163
• [3.11] gh-101100: Fix Sphinx nitpicks in library/numbers.rst (GH-113162) #113181
• [3.12] gh-101100: Fix Sphinx nitpicks in library/numbers.rst (GH-113162) #113182
• [3.12] gh-101100: Fix various Sphinx warnings for dunder references in the library/ directory (GH-113163) #113183
• [3.11] gh-101100: Fix various Sphinx warnings for dunder references in the library/ directory (GH-113163) #113184
• gh-101100: Fix Sphinx warnings in library/tarfile.rst #113237
• [3.12] gh-101100: Fix Sphinx warnings in library/tarfile.rst (GH-113237) #113244
• [3.11] gh-101100: Fix Sphinx warnings in library/tarfile.rst (GH-113237) #113245
• gh-101100: Fix Sphinx warnings in library/ast.rst #113289
• [3.12] gh-101100: Fix Sphinx warnings in library/ast.rst (GH-113289) #113290
• [3.11] gh-101100: Fix Sphinx warnings in library/ast.rst (GH-113289) #113291
• gh-101100: Fix Sphinx warnings in howto/isolating-extensions.rst #113493
• gh-101100: Fix Sphinx warnings in c-api/float.rst #113494
• gh-101100: Fix Sphinx warnings in library/bisect.rst #113496
• [3.12] gh-101100: Fix Sphinx warnings in howto/isolating-extensions.rst (GH-113493) #113497
• [3.11] gh-101100: Fix Sphinx warnings in howto/isolating-extensions.rst (GH-113493) #113498
• gh-101100: Fix Sphinx warnings in library/calendar.rst #113500
• gh-101100: Fix Sphinx warnings in library/cmd.rst #113502
• [3.12] gh-101100: Fix Sphinx warnings in library/bisect.rst (GH-113496) #113504
• [3.11] gh-101100: Fix Sphinx warnings in library/bisect.rst (GH-113496) #113505
• [3.11] gh-101100: Fix Sphinx warnings in library/calendar.rst (GH-113500) #113508
• [3.12] gh-101100: Fix Sphinx warnings in library/calendar.rst (GH-113500) #113509
• [3.11] gh-101100: Fix Sphinx warnings in library/cmd.rst (GH-113502) #113510
• [3.12] gh-101100: Fix Sphinx warnings in library/cmd.rst (GH-113502) #113511
• [3.12] gh-101100: Fix Sphinx warnings in library/random.rst (GH-112981) #113551
• [3.11] gh-101100: Fix Sphinx warnings in library/random.rst (GH-112981) #113552
• gh-101100: Fix Sphinx warnings in c-api/structures.rst #113564
• gh-101100: Fix Sphinx warnings in library/configparser.rst #113598
• [3.12] gh-101100: Fix Sphinx warnings in library/configparser.rst (GH-113598) #113599
• [3.11] gh-101100: Fix Sphinx warnings in library/configparser.rst (GH-113598) #113600
• gh-101100: Fix Sphinx warnings from removed ~! references #113629
• [3.12] gh-101100: Fix Sphinx warnings from removed ~! references (GH-113629) #113641
• [3.11] gh-101100: Fix Sphinx warnings from removed ~! references (GH-113629) #113642
• gh-101100: Fix Sphinx warnings for removed dead batteries #113669
• [3.12] gh-101100: Fix Sphinx warnings for removed dead batteries (GH-113669) #113681
• gh-101100: Fix Sphinx warnings for 2.6 deprecations and removals #113725
• [3.12] gh-101100: Fix Sphinx warnings for 2.6 deprecations and removals (GH-113725) #113734
• [3.11] gh-101100: Fix Sphinx warnings for 2.6 deprecations and removals (GH-113725) #113735
• gh-101100: Fix Sphinx warnings in library/pyclbr.rst #113739
• [3.12] gh-101100: Fix Sphinx warnings in library/pyclbr.rst (GH-113739) #113748
• [3.11] gh-101100: Fix Sphinx warnings in library/pyclbr.rst (GH-113739) #113749
• gh-101100: Fix Sphinx warnings for 2.6 port-specific deprecations #113752
• [3.12] gh-101100: Fix Sphinx warnings for 2.6 port-specific deprecations (GH-113752) #113846
• [3.11] gh-101100: Fix Sphinx warnings for 2.6 port-specific deprecations (GH-113752) #113847
• gh-101100: Fix Sphinx Lint warnings in Misc/ #113946
• [3.12] gh-101100: Fix Sphinx Lint warnings in Misc/ (GH-113946) #113998
• [3.11] gh-101100: Fix Sphinx Lint warnings in Misc/ (GH-113946) #114001
• gh-101100: Fix Sphinx warnings in howto/urllib2.rst and library/http.client.rst #114060
• [3.12] gh-101100: Fix Sphinx warnings in howto/urllib2.rst and library/http.client.rst (GH-114060) #114063
• [3.11] gh-101100: Fix Sphinx warnings in howto/urllib2.rst and library/http.client.rst (GH-114060) #114064
• gh-101100: Fix Sphinx warnings in reference/expressions.rst #114194
• gh-101100: fix sphinx warnings in reference/datamodel.rst #114280
• gh-101100: Fix Sphinx warnings from PEP 3108 stdlib re-organisation #114327
• gh-101100: Fix sphinx warnings in Doc/c-api/memory.rst #114373
• [3.12] gh-101100: Fix sphinx warnings in Doc/c-api/memory.rst (GH-114373) #114377
• [3.11] gh-101100: Fix sphinx warnings in Doc/c-api/memory.rst (GH-114373) #114378
• gh-101100: Fix sphinx warnings in Doc/library/locale.rst #114425
• [3.12] gh-101100: Fix Sphinx warnings in reference/expressions.rst (GH-114194) #114436
• [3.11] gh-101100: Fix Sphinx warnings in reference/expressions.rst (GH-114194) #114437
• gh-101100: Fix sphinx warnings in asyncio-task.rst #114469
• [3.12] gh-101100: Fix sphinx warnings in Doc/library/locale.rst (GH-114425) #114477
• [3.11] gh-101100: Fix sphinx warnings in Doc/library/locale.rst (GH-114425) #114478
• [3.11] gh-101100: Fix sphinx warnings in asyncio-task.rst (GH-114469) #114518
• [3.12] gh-101100: Fix sphinx warnings in asyncio-task.rst (GH-114469) #114519
• gh-101100: Fix sphinx warnings in concurrent.futures.rst #114521
• [3.12] gh-101100: Fix sphinx warnings in concurrent.futures.rst (GH-114521) #114525
• [3.11] gh-101100: Fix sphinx warnings in concurrent.futures.rst (GH-114521) #114526
• [3.12] gh-101100: Fix Sphinx warnings in c-api/structures.rst (GH-113564) #114527
• gh-101100: Fix Sphinx warnings in whatsnew/3.11.rst and related #114531
• gh-101100: Fix sphinx warnings in c-api/file.rst #114546
• [3.12] gh-101100: Fix sphinx warnings in c-api/file.rst (GH-114546) #114584
• [3.11] gh-101100: Fix sphinx warnings in c-api/file.rst (GH-114546) #114585
• gh-101100: Fix sphinx warnings in library/email.mime.rst #114635
• [3.12] gh-101100: Fix sphinx warnings in library/email.mime.rst (GH-114635) #114640
• [3.11] gh-101100: Fix sphinx warnings in library/email.mime.rst (GH-114635) #114641
• gh-101100: Fix sphinx warnings in reference/import.rst #114646
• [3.12] gh-101100: Fix Sphinx warnings in whatsnew/3.11.rst and related (GH-114531) #114649
• [3.11] gh-101100: Fix Sphinx warnings in whatsnew/3.11.rst and related (GH-114531) #114650
• [3.12] gh-101100: Fix sphinx warnings in reference/import.rst (GH-114646) #114652
• [3.11] gh-101100: Fix sphinx warnings in reference/import.rst (GH-114646) #114654
• gh-101100: Fix references in csv docs #114658
• gh-101100: Fix datetime reference warnings #114661
• gh-101100: Fix sphinx warnings in Doc/c-api/memoryview.rst #114669
• gh-101100: Fix sphinx warnings in library/enum.rst #114696
• [3.12] gh-101100: Fix sphinx warnings in Doc/c-api/memoryview.rst (GH-114669) #114704
• [3.11] gh-101100: Fix sphinx warnings in Doc/c-api/memoryview.rst (GH-114669) #114705
• [3.12] gh-101100: Fix Sphinx warnings in whatsnew/2.2.rst (GH-112366) #114711
• [3.11] gh-101100: Fix Sphinx warnings in whatsnew/2.2.rst (GH-112366) #114712
• [3.12] gh-101100: Fix datetime reference warnings (GH-114661) #114716
• [3.11] gh-101100: Fix datetime reference warnings (GH-114661) #114718
• gh-101100: Fix Sphinx reference warnings in the glossary #114729
• gh-101100: Fix class reference in library/test.rst #114769
• gh-101100: Update .nitignore (after accepting library/test.rst changes) #114770
• [3.12] gh-101100: Fix references in csv docs (GH-114658) #114771
• [3.11] gh-101100: Fix references in csv docs (GH-114658) #114773
• gh-101100: Fix sphinx warnings in c-api/gcsupport.rst #114786
• [3.11] gh-101100: Fix class reference in library/test.rst (GH-114769) #114793
• [3.12] gh-101100: Fix class reference in library/test.rst (GH-114769) #114794
• gh-101100: Clean up Doc/c-api/exceptions.rst and Doc/c-api/sys.rst #114825
• gh-101100: Fix sphinx warnings in howto/logging.rst #114846
• [3.11] gh-101100: Fix sphinx warnings in howto/logging.rst (GH-114846) #114872
• [3.12] gh-101100: Fix sphinx warnings in howto/logging.rst (GH-114846) #114878
• gh-101100: Fix dangling references in test.rst #114958
• [3.12] gh-101100: Fix Sphinx reference warnings in the glossary (GH-114729) #114969
• [3.11] gh-101100: Fix Sphinx reference warnings in the glossary (GH-114729) #114970
• gh-101100: Fix dangling references in pickle.rst #114972
• gh-101100: Fix extending.rst #114981
• gh-101100: Fix load_module ref #114982
• gh-101100: Fix dangling refs in bdb.rst #114983
• [3.12] gh-101100: Fix Sphinx warnings from PEP 3108 stdlib re-organisation (GH-114327) #114988
• [3.11] gh-101100: Fix Sphinx warnings from PEP 3108 stdlib re-organisation (GH-114327) #114989
• [3.11] gh-101100: Fix dangling references in pickle.rst (GH-114972) #114992
• [3.12] gh-101100: Fix dangling references in pickle.rst (#114972) #114999
• gh-101100: Fix Py_DEBUG dangling references #115003
• [3.12] gh-101100: Fix Py_DEBUG dangling Sphinx references (GH-115003) #115135
• [3.11] gh-101100: Fix Py_DEBUG dangling Sphinx references (#115003) #115141
• [3.12] gh-101100: Fix sphinx warnings in library/enum.rst (GH-114696) #115208
• [3.11] gh-101100: Fix sphinx warnings in library/enum.rst (GH-114696) #115209
• [3.12] gh-101100: Fix sphinx warnings in c-api/gcsupport.rst (GH-114786) #115263
• [3.11] gh-101100: Fix dangling refs in bdb.rst (GH-114983) #115284
• [3.12] gh-101100: Fix dangling refs in bdb.rst (#114983) #115297
• [3.12] gh-101100: Clean up Doc/c-api/exceptions.rst and Doc/c-api/sys.rst (GH-114825) #115308
• [3.11] Clean up Doc/c-api/exceptions.rst and Doc/c-api/sys.rst #114825 (gh-101100) #115310
• [3.11] gh-101100: Clean up Doc/c-api/exceptions.rst and Doc/c-api/sys.rst (#114825) #115311
• gh-101100: Fix Sphinx warnings in whatsnew/2.7.rst and related #115319
• [3.12] gh-101100: Fix Sphinx warnings in whatsnew/2.7.rst and related (GH-115319) #115330
• [3.11] gh-101100: Fix Sphinx warnings in whatsnew/2.7.rst and related (GH-115319) #115331
• [3.11] gh-101100: Fix sphinx warnings in c-api/gcsupport.rst (GH-114786) #115430
• gh-101100: Fix Sphinx warnings in whatsnew/3.1.rst #115575
• gh-101100: Fix Sphinx warnings in whatsnew/3.2.rst #115580
• [3.12] gh-101100: Fix Sphinx warnings in whatsnew/3.1.rst (GH-115575) #115587
• [3.11] gh-101100: Fix Sphinx warnings in whatsnew/3.1.rst (GH-115575) #115588
• [3.12] gh-101100: Fix Sphinx warnings in whatsnew/3.2.rst (GH-115580) #115589
• [3.11] gh-101100: Fix Sphinx warnings in whatsnew/3.2.rst (GH-115580) #115590
• gh-101100: Fix broken xrefs in fcntl module doc #115691
• [3.12] gh-101100: Fix Sphinx warnings in whatsnew/2.0.rst (GH-112351) #115902
• [3.11] gh-101100: Fix Sphinx warnings in whatsnew/2.0.rst (GH-112351) #115903
• [3.12] gh-101100: Fix broken xrefs in fcntl module doc (GH-115691) #115924
• [3.11] gh-101100: Fix broken xrefs in fcntl module doc (GH-115691) #115925
• [3.12] gh-101100: Fix Sphinx warnings in whatsnew/2.1.rst (GH-112357) #115932
• [3.11] gh-101100: Fix Sphinx warnings in whatsnew/2.1.rst (GH-112357) #115933
• gh-101100: Fix Sphinx warnings in library/pydoc.rst #116913
• [3.12] gh-101100: Fix Sphinx warnings in library/pydoc.rst (GH-116913) #117037
• [3.11] gh-101100: Fix Sphinx warnings in library/pydoc.rst (GH-116913) #117038
• gh-101100: Fix Sphinx warnings in library/faulthandler.rst #118353
• gh-101100: Fix Sphinx warnings in whatsnew/3.10.rst #118356
• gh-101100: Fix Sphinx warnings in whatsnew/3.9.rst #118364
• [3.12] gh-101100: Fix Sphinx warnings in whatsnew/3.9.rst (GH-118364) #118365
• [3.12] gh-101100: Fix Sphinx warnings in library/faulthandler.rst (GH-118353) #118366
• [3.12] gh-101100: Fix Sphinx warnings in whatsnew/3.10.rst (GH-118356) #118367
• gh-101100: Fix Sphinx warnings in library/unittest.mock.rst #124106
• gh-101100: Add a table of class attributes to the "Custom classes" section of the data model docs #124480
• [3.13] gh-101100: Add a table of class attributes to the "Custom classes" section of the data model docs (#124480) #124556
• [3.12] gh-101100: Add a table of class attributes to the "Custom classes" section of the data model docs (#124480) #124558
• gh-101100: Make __subclasses__ doctest stable #124577
• [3.13] gh-101100: Make __subclasses__ doctest stable (GH-124577) #124579
• [3.12] gh-101100: Make __subclasses__ doctest stable (GH-124577) #124580
• gh-101100: Consolidate documentation on ModuleType attributes #124709
• [3.13] gh-101100: Fix Sphinx warnings in library/unittest.mock.rst (GH-124106) #125190
• [3.12] gh-101100: Fix Sphinx warnings in library/unittest.mock.rst (GH-124106) #125191
• [3.13] gh-101100: Consolidate documentation on ModuleType attributes (#124709) #125208
• [3.12] gh-101100: Consolidate documentation on ModuleType attributes (#124709) #125211
• gh-101100: Fix Sphinx warnings about list methods #127054
• gh-101100: Fix sphinx warnings in howto/* #127084
• gh-101100: Fix sphinx warnings of removed opcodes #127222
• [3.13] gh-101100: Fix sphinx warnings of removed opcodes (GH-127222) #127239
• [3.12] gh-101100: Fix sphinx warnings of removed opcodes (GH-127222) #127240
• [3.13] gh-101100: Fix sphinx warnings in howto/* (GH-127084) #127287
• [3.12] gh-101100: Fix sphinx warnings in howto/* (GH-127084) #127311
• [3.13] gh-101100: Fix Sphinx warnings about list methods (GH-127054) #127511
• [3.12] gh-101100: Fix Sphinx warnings about list methods (GH-127054) #127512
• gh-101100: Fix sphinx warnings in whatsnew/3.0.rst #127662
• gh-101100: amend references starting with !~ in gh-127054 #127684
• [3.13] gh-101100: amend references starting with !~ in gh-127054 (GH-127684) #127692
• [3.12] gh-101100: amend references starting with !~ in gh-127054 (GH-127684) #127693
• [3.13] gh-101100: Fix sphinx warnings in whatsnew/3.0.rst (GH-127662) #127783
• [3.12] gh-101100: Fix sphinx warnings in whatsnew/3.0.rst (GH-127662) #127784
• gh-101100: Docs: Fix some typos in the document #129988
• [3.13] gh-101100: Docs: Fix some typos in the document (GH-129988) #129997
• [3.12] gh-101100: Docs: Fix some typos in the document (GH-129988) #129998
• gh-101100: Fix sphinx warnings in readline.rst #130300
• [3.13] gh-101100: Fix sphinx warnings in readline.rst (GH-130300) #130346
• [3.12] gh-101100: Fix sphinx warnings in readline.rst (GH-130300) #130347
• gh-101100: Fix Sphinx documentation warnings in collections.rst #130629
• gh-101100: Fix sphinx warnings in library/email.errors.rst #130774
• [3.13] gh-101100: Fix Sphinx documentation warnings in collections.rst (GH-130629) #130779
• [3.12] gh-101100: Fix sphinx warnings in library/email.errors.rst (GH-130774) #130780
• [3.13] gh-101100: Fix sphinx warnings in library/email.errors.rst (GH-130774) #130781
• [3.12] gh-101100: Fix Sphinx documentation warnings in collections.rst (GH-130629) #130782
• gh-101100: Fix sphinx warnings in library/asyncio-subprocess.rst #130994
• [3.13] gh-101100: Fix sphinx warnings in library/asyncio-subprocess.rst (GH-130994) #131074
• [3.12] gh-101100: Fix sphinx warnings in library/asyncio-subprocess.rst (GH-130994) #131075
• gh-101100: Fix sphinx warnings in library/plistlib.rst #132422
• [3.13] gh-101100: Fix sphinx warnings in library/plistlib.rst (GH-132422) #132485
• gh-101100: Fix Sphinx warnings in library/decimal.rst #134303
• [3.14] gh-101100: Fix Sphinx warnings in library/decimal.rst (GH-134303) #134338
• [3.13] gh-101100: Fix Sphinx warnings in library/decimal.rst (GH-134303) #134339
• gh-101100: Fix sphinx warnings in whatsnew/3.9 #136163
• gh-101100: Fix sphinx warnings in Doc/library/exceptions.rst #136309
• gh-101100: Fix references in http.cookiejar docs #114658 #136238
• [3.13] gh-101100: Fix references in http.cookiejar docs (GH-136238) #136317
• [3.14] gh-101100: Fix references in http.cookiejar docs (GH-136238) #136318
• gh-101100: Fix Sphinx warnings in library/email.compat32-message.rst #136323
• [3.14] gh-101100: Fix sphinx warnings in whatsnew/3.9 (GH-136163) #136372
• [3.13] gh-101100: Fix sphinx warnings in whatsnew/3.9 (GH-136163) #136373
• [3.14] gh-101100: Fix Sphinx warnings in library/email.compat32-message.rst (GH-136323) #136389
• [3.13] gh-101100: Fix Sphinx warnings in library/email.compat32-message.rst (GH-136323) #136390
• gh-101100: Fix sphinx warnings in whatsnew/3.11.rst #136402
• [3.13] gh-101100: Fix sphinx warnings in whatsnew/3.11.rst (GH-136402) #136404
• [3.14] gh-101100: Fix sphinx warnings in whatsnew/3.11.rst (GH-136402) #136405
• [3.14] gh-101100: Fix sphinx warnings in Doc/library/exceptions.rst (GH-136309) #136414
• [3.13] gh-101100: Fix sphinx warnings in Doc/library/exceptions.rst (GH-136309) #136415
• gh-101100: Fix sphinx warnings in Doc/library/functools.rst #136424
• gh-101100: Fix sphinx warnings in library/email.parser.rst #136475
• [3.14] gh-101100: Fix sphinx warnings in library/email.parser.rst (GH-136475) #136532
• [3.13] gh-101100: Fix sphinx warnings in library/email.parser.rst (GH-136475) #136533
• [3.14] gh-101100: Fix sphinx warnings in Doc/library/functools.rst (GH-136424) #136552
• [3.13] gh-101100: Fix sphinx warnings in Doc/library/functools.rst (GH-136424) #136554
• gh-101100: Fix sphinx warnings in Doc/library/platform.rst #136562
• [3.14] gh-101100: Fix sphinx warnings in Doc/library/platform.rst (GH-136562) #136597
• [3.13] gh-101100: Fix sphinx warnings in Doc/library/platform.rst (GH-136562) #136598
• gh-101100: Resolve reference warnings in library/xml.sax.handler.rst #136612
• Partially revert "gh-101100: Fix sphinx warnings in library/email.parser.rst (#136475)" #136629
• [3.14] Partially revert "gh-101100: Fix sphinx warnings in library/email.parser.rst (GH-136475)" (GH-136629) #136646
• [3.13] Partially revert "gh-101100: Fix sphinx warnings in library/email.parser.rst (GH-136475)" (GH-136629) #136647
• GH-101100: Resolve reference warnings in whatsnew/3.10.rst #138408
• GH-101100: Resolve reference warnings in whatsnew/3.8.rst #138409
• GH-101100: Resolve reference warnings in whatsnew/3.7.rst #138410
• GH-101100: Resolve reference warnings in whatsnew/3.6.rst #138411
• GH-101100: Resolve reference warnings in whatsnew/3.5.rst #138412
• GH-101100: Resolve reference warnings in whatsnew/3.4.rst #138413
• GH-101100: Resolve reference warnings in whatsnew/3.3.rst #138414
• GH-101100: Resolve reference warnings in whatsnew/2.7.rst #138415
• GH-101100: Resolve reference warnings in using/windows.rst #138416
• GH-101100: Resolve reference warnings in extending/extending.rst #138417
• gh-101100: Resolve reference warnings in reference/ #138418
• GH-101100: Resolve reference warnings in library/stdtypes.rst #138420
• [3.14] gh-101100: Resolve reference warnings in library/xml.sax.handler.rst (GH-136612) #138421
• [3.13] gh-101100: Resolve reference warnings in library/xml.sax.handler.rst (GH-136612) #138422
• [3.14] GH-101100: Resolve reference warnings in whatsnew/3.7.rst (GH-138410) #138423
• [3.13] GH-101100: Resolve reference warnings in whatsnew/3.7.rst (GH-138410) #138424
• [3.14] GH-101100: Resolve reference warnings in whatsnew/3.3.rst (GH-138414) #138435
• [3.13] GH-101100: Resolve reference warnings in whatsnew/3.3.rst (GH-138414) #138436
• [3.14] GH-101100: Resolve reference warnings in whatsnew/3.8.rst (GH-138409) #138437
• [3.13] GH-101100: Resolve reference warnings in whatsnew/3.8.rst (GH-138409) #138438
• [3.14] GH-101100: Resolve reference warnings in whatsnew/2.7.rst (GH-138415) #138441
• [3.13] GH-101100: Resolve reference warnings in whatsnew/2.7.rst (GH-138415) #138442
• [3.14] GH-101100: Resolve reference warnings in whatsnew/3.4.rst (GH-138413) #138443
• [3.13] GH-101100: Resolve reference warnings in whatsnew/3.4.rst (GH-138413) #138444
• [3.14] GH-101100: Resolve reference warnings in extending/extending.rst (GH-138417) #138446
• [3.13] GH-101100: Resolve reference warnings in extending/extending.rst (GH-138417) #138447
• [3.14] GH-101100: Resolve reference warnings in whatsnew/3.6.rst (GH-138411) #138455
• [3.13] GH-101100: Resolve reference warnings in whatsnew/3.6.rst (GH-138411) #138456
• [3.14] GH-101100: Resolve reference warnings in whatsnew/3.5.rst (GH-138412) #138459
• [3.13] GH-101100: Resolve reference warnings in whatsnew/3.5.rst (GH-138412) #138460
• [3.14] GH-101100: Resolve reference warnings in using/windows.rst (GH-138416) #138461
• [3.13] GH-101100: Resolve reference warnings in using/windows.rst (#138416) #138463
• [3.14] GH-101100: Resolve reference warnings in whatsnew/3.10.rst (GH-138408) #138480
• gh-138481
• gh-138680
• gh-138681
• gh-138464
• gh-138683
• gh-139236
• gh-139568
• gh-139569
• gh-139572
• gh-139576
• gh-139592
• gh-139636
• gh-139787
• gh-139788
• gh-139832
• gh-139833
• gh-139835
• gh-139910
• gh-139912
• gh-139930
• gh-139966
• gh-139967
• gh-139991
• gh-140023
• gh-140084
• gh-140085
• gh-140109
• gh-140194
• gh-140352
• gh-140353
• gh-141827
• gh-141853
• gh-141854
• gh-141855
• gh-141857
• gh-142300
• gh-142345
• gh-145794
• gh-145795

[encukou]

See also: https://discuss.python.org/t/broken-references-in-sphinx-docs/19463

IMO, we should fix these. Many are actual issues in the documentation.

Here's a proof-of-concept GH Action that complains about nitpicks in changed files only: encukou@e97d91f
Feel free to take it, I don't think I'll have time for this soon.

[CAM-Gerlach]

IMO, we should fix these. Many are actual issues in the documentation.

Yes, definitely; I've been gradually helping on the docs I've/we've touched anyway, though it is a long term project. I've found a number of things that were undocumented, as well as a number of other real issues through that, e.g. on the sqlite3 module that Erlend and I fixed.

Most of them are innocent, like using :const: while referring to a constant defined in another file, or using :meth:__init__ to speak about the concept of an init method.

I'd argue neither is exactly innocent:

• For the first, unless there's some particular reason not to, it usually makes sense to actually cross reference the constant, so the reader can find out more, and be explicit about it's location at least in the source (since ~ can hide that in the rendered output if not desired). This also means if the constant is renamed, moved or removed, Sphinx will issue a warning about it.
• For the second, doing :meth:`~object.__init__` to cross reference the full description of an __init__ method will often still have value to readers, at least on first usage in a context, and doesn't take up any more space. We could potentially extend the :meth: role to automatically prepend a default name, i.e. object, to :meth: and :attr: that only have a single component, and perform the lookup with that—though the Sphinx built in roles are not the best structured to be able to extend easily without copying a fair bit of code.

For the innocent usages of rst markers, there's two fixes:

There's a third, much simpler and better fix. If the link isn't desired, every Sphinx cross-reference role supports prepending ! to prevent Sphinx from trying to resolve the reference, which avoids both the warning and the (very slight) build-time lookup cost, while preserving both all the information in the source, and the formatting in the output (since the formatting of named roles and regular literals is not the same, at least in our current theme), while being easier than both (just add one character). So, you could just do:

:const:`!IGNORECASE`

[sobolevn]

I've sent an example PR with the fix for enum module: #101122

The dev experience was plesant, because on the second run sphinx only rebuilds (and warns about) changed files:

[CAM-Gerlach]

As a general note of caution, especially when submitting PRs fixing these sorts of widespread and potentially nitpicky (heh) docs defects, especially when in cases like this there are a number of different possibilities to handle each warning instance, we should take care to avoid the folly of large "omnibus" PRs (as Guido likes to call them) and take care to consider each specific change we're making holistically, and ensure that we're picking the approach that best serves the reader in for each specific context, as opposed to just applying one type of fix mechanically to all instances, or even worse arbitrarily picking one or another each time without careful thought and consideration that might fix the warning but be an overall regression.

Otherwise, if we're too focused solely on the narrow objective of getting rid of the warnings by whatever means, as opposed to the broader goal of improving the overall quality of the docs, we risk both doing exactly the opposite of the latter, and consuming the limited time and churn budget of core developers and other reviewers on changes with little or even negative practical benefit.

[encukou]

That's the reasoning behind teaching the CI to only warn, and only on changed files.

[hugovk]

To enable this, it would be really useful if Sphinx had more granular config for the warnings/errors, similar to Flake8.

For example, we could enable nitpicky only for certain directories and files, and expand as more are cleaned. And possibly in combination with an exclude option.

Similarly, we may only want to enable/disable nitpicky for certain classes of warnings/errors.

That would allow us to iteratively fix things, and keep them fixed.

cc @AA-Turner