Fix Sphinx warnings in the C API documentation

[vstinner]

Recently, I saw a growing numbers of Sphinx warnings displayed as annotations which make reviews harder.

I create this issue to track changes fixing warnings.

See also gh-106948 which populates nitpick_ignore of Doc/conf.py with standard C functions, variables, macros and env vars.

Linked PRs

• gh-107298: Fix doc references to undocumented modules #107300
• gh-107298: Fix Sphinx warnings in the C API doc #107302
• gh-107298: Fix references to undocumented APIs #107304
• gh-107298: Docs: add targets for some :c:member: and :c:macro: references #107316
• gh-107298: Fix more Sphinx warnings in the C API doc #107329
• [3.12] gh-107298: Docs: add targets for some :c:member: and :c:macro: references (GH-107316) #107332
• [3.11] gh-107298: Docs: add targets for some :c:member: and :c:macro: references (GH-107316) #107333
• gh-107298: Fix yet more Sphinx warnings in the C API doc #107345
• [3.12] gh-107298: Fix doc references to undocumented modules (GH-107300) #107370
• [3.11] gh-107298: Fix doc references to undocumented modules (GH-107300) #107371
• [3.11] gh-107298: Fix Sphinx warnings in the C API doc (GH-107302) #107373
• [3.12] gh-107298: Fix Sphinx warnings in the C API doc (GH-107302) #107375
• [3.12] gh-107298: Fix more Sphinx warnings in the C API doc (GH-107329) #107376
• [3.11] gh-107298: Fix more Sphinx warnings in the C API doc (GH-107329) #107377
• [3.12] gh-107298: Fix yet more Sphinx warnings in the C API doc (GH-107345) #107380
• [3.11] gh-107298: Fix yet more Sphinx warnings in the C API doc (GH-107345) #107381
• gh-107298: Fix C API Buffer documentation #108011
• gh-107298: Add standard exceptions and warnings in the nitpick_ignore list #108029
• gh-107298: Fix C API datetime documentation #108034
• [3.11] gh-107298: Fix C API Buffer documentation (GH-108011) #108041
• [3.12] gh-107298: Fix C API Buffer documentation (GH-108011). #108048
• [3.12] gh-107298: Add standard exceptions and warnings in the nitpick_ignore list (GH-108029) #108070
• [3.11] gh-107298: Add standard exceptions and warnings in the nitpick_ignore list (GH-108029) #108071
• gh-107298: Fix some references in the C API documentation #108072
• [3.12] gh-107298: Fix some references in the C API documentation (GH-108072) #108074
• [3.11] gh-107298: Fix some references in the C API documentation (GH-108072) #108076
• gh-107298: Fix references to deprecated and removed PyUnicode C API #108077
• [3.12] gh-107298: Fix references to deprecated and removed PyUnicode C API (GH-108077) #108225
• [3.11] gh-107298: Fix references to deprecated and removed PyUnicode C API (GH-108077) #108226
• [3.11] gh-107298: Fix C API datetime documentation (GH-108034) #108233
• [3.12] gh-107298: Fix C API datetime documentation (GH-108034). #108234
• gh-107298: Fix numerous ref errors and typos in the C API docs #108258
• [3.12] gh-107298: Fix numerous ref errors and typos in the C API docs (GH-108258) #108284
• [3.11] gh-107298: Fix numerous ref errors and typos in the C API docs (GH-108258) #108290
• gh-107298: Fix a few more refs in the C API docs #108361
• gh-107298: Document PyAPI_DATA() macro #109129
• gh-107298: Document doesn't link to PyAPI_DATA() #109236
• [3.12] gh-107298: Document PyMODINIT_FUNC macro (GH-109236) #109947
• [3.11] gh-107298: Document PyMODINIT_FUNC macro (#109236) #109948

[vstinner]

I abandoned my previous PRs: PR #107164 and PR #107274.

See also:

• PR gh-106948: Docs: Disable links for C standard library functions, OS utility functions and system calls #107062
• PR gh-107091: Use :c:var: consistently for Py_Version #107063
• Issue Use the C domain roles consistently in the documentation #107091

[vstinner]

I extracted these comments from the CI job to generate warnings locally: check.sh script.

set -Eeuo pipefail
# Build docs with the '-n' (nit-picky) option; write warnings to file
make -C Doc/ PYTHON=../python SPHINXOPTS="-q -n -W --keep-going -w sphinx-warnings.txt" html
python Doc/tools/check-warnings.py \
  --fail-if-regression \
  --fail-if-improved

[hugovk]

See also #107298 as an umbrella issue for Sphinx warnings.

[vstinner]

See also #107298 as an umbrella issue for Sphinx warnings.

Wait, is it the number of this issue? I'm now confused.

[CAM-Gerlach]

@vstinner I'm guessing @hugovk meant #101100 and just accidentally pasted/autocompleted the mistaken issue number

[serhiy-storchaka]

I updated lists after fixing some warnings and excluded references from NEWS and automatically generated lists of all C API names.

[vstinner]

The number of Sphinx warnings in the C API documentation is way lower! I'm no longer annoyed by Sphinx warnings unrelated to my changes when I modify C code and/or C API documentation!

Thanks everybody who helped to fix these warnings. I close this issue.