Description

vstinner

opened on Jul 26, 2023

Issue body actions

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

Activity

1. vstinner

   added

   type-bugAn unexpected behavior, bug, or errorAn unexpected behavior, bug, or error

   docsDocumentation in the Doc dirDocumentation in the Doc dir

   on Jul 26, 2023
2. vstinner

   added 4 commits that reference this issue on Jul 26, 2023

   pythongh-107298: Fix doc references to undocumented modules

   3438899

   pythongh-107298: Fix Sphinx warnings in the C API doc

   ce998cf

   gh-107298: Fix doc references to undocumented modules (#107300)

   87b3902

   pythongh-107298: Fix Sphinx warnings in the C API doc

   b993a6c
3. vstinner commented on Jul 26, 2023

   

   vstinner

   on Jul 26, 2023

   MemberAuthor

   More actions

   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
4. vstinner

   added a commit that references this issue on Jul 26, 2023

   pythongh-107298: Fix references to undocumented APIs

   ed05188
5. vstinner commented on Jul 26, 2023

   

   vstinner

   on Jul 26, 2023

   MemberAuthor

   More actions

   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
6. hugovk commented on Jul 26, 2023

   

   hugovk

   on Jul 26, 2023

   Member

   More actions

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

   Reacted by Alex Waygood
7. serhiy-storchaka

   added 3 commits that reference this issue on Jul 26, 2023

   pythongh-107298: Docs: add targets for some :c:member: and :c:macro: …

   e15b0f6

   pythongh-107298: Docs: add targets for some :c:member: and :c:macro: …

   0e1f4a9

   pythongh-107298: Docs: add targets for some :c:member: and :c:macro: …

   310bf2c
8. vstinner commented on Jul 26, 2023

   

   vstinner

   on Jul 26, 2023

   MemberAuthor

   More actions

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

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

   added a commit that references this issue on Jul 26, 2023

   pythongh-107298: Fix Sphinx warnings in the C API doc

   acc6808
10. 74 remaining items
11. serhiy-storchaka

    added 2 commits that reference this issue on Aug 23, 2023

    pythongh-107298: Fix few more refs in the C API docs

    ec6b1aa

    gh-107298: Fix a few more refs in the C API docs (GH-108361)

    422f81b
12. serhiy-storchaka commented on Aug 23, 2023

    

    serhiy-storchaka

    on Aug 23, 2023

    Member

    More actions

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

    added 5 commits that reference this issue on Sep 8, 2023

    pythongh-107298: Document PyAPI_DATA() macro

    1c9a991

    pythongh-107298: Document doesn't link to PyAPI_DATA()

    cbd269f

    pythongh-107298: Document doesn't link to PyAPI_DATA()

    c3ac141

    pythongh-107298: Document doesn't link to PyAPI_DATA()

    5eba491

    pythongh-107298: Document doesn't link to PyAPI_DATA()

    5847580
14. vstinner commented on Sep 13, 2023

    

    vstinner

    on Sep 13, 2023

    MemberAuthor

    More actions

    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.

    Reacted by Hugo van Kemenade
15. vstinner

    closed this as completedon Sep 13, 2023
16. vstinner

    added 2 commits that reference this issue on Sep 13, 2023

    pythongh-107298: Document doesn't link to PyAPI_DATA()

    584f47d

    gh-107298: Document PyMODINIT_FUNC macro (#109236)

    d7a27e5
17. miss-islington

    added a commit that references this issue on Sep 27, 2023

    pythongh-107298: Document PyMODINIT_FUNC macro (pythonGH-109236)

    2d07b75
18. vstinner

    added a commit that references this issue on Sep 27, 2023

    [3.11] gh-107298: Document PyMODINIT_FUNC macro (#109236) (#109948)

    d951aae
19. Yhg1s

    added a commit that references this issue on Sep 27, 2023

    [3.12] gh-107298: Document PyMODINIT_FUNC macro (GH-109236) (#109947)

    fc4fddb

Issue actions