pythongh-106948: Add Doc/nitpick_ignore.yml config file

Maintaining nitpick_ignore Python list in conf.py is a burden. Add a YAML configuration file which is easier to maintain. Ignore also standard C types in the "c:identifier" domain.
vstinner · Jul 25, 2023 · 133530d · 133530d
1 parent 33838fe
commit 133530d
Show file tree

Hide file tree

Showing 4 changed files with 109 additions and 76 deletions.
diff --git a/Doc/conf.py b/Doc/conf.py
@@ -10,6 +10,8 @@
 sys.path.append(os.path.abspath('tools/extensions'))
 sys.path.append(os.path.abspath('includes'))
 
+import yaml
+
 # General configuration
 # ---------------------
 
@@ -76,82 +78,32 @@
 if venvdir is not None:
     exclude_patterns.append(venvdir + '/*')
 
-nitpick_ignore = [
-    # Standard C functions
-    ('c:func', 'calloc'),
-    ('c:func', 'dlopen'),
-    ('c:func', 'exec'),
-    ('c:func', 'fcntl'),
-    ('c:func', 'fork'),
-    ('c:func', 'free'),
-    ('c:func', 'gmtime'),
-    ('c:func', 'localtime'),
-    ('c:func', 'main'),
-    ('c:func', 'malloc'),
-    ('c:func', 'printf'),
-    ('c:func', 'realloc'),
-    ('c:func', 'snprintf'),
-    ('c:func', 'sprintf'),
-    ('c:func', 'stat'),
-    ('c:func', 'system'),
-    ('c:func', 'vsnprintf'),
-    # Standard C types
-    ('c:type', 'FILE'),
-    ('c:type', '__int'),
-    ('c:type', 'intmax_t'),
-    ('c:type', 'off_t'),
-    ('c:type', 'ptrdiff_t'),
-    ('c:type', 'siginfo_t'),
-    ('c:type', 'size_t'),
-    ('c:type', 'ssize_t'),
-    ('c:type', 'time_t'),
-    ('c:type', 'uintmax_t'),
-    ('c:type', 'va_list'),
-    ('c:type', 'wchar_t'),
-    # Standard C macros
-    ('c:macro', 'LLONG_MAX'),
-    ('c:macro', 'LLONG_MIN'),
-    ('c:macro', 'LONG_MAX'),
-    ('c:macro', 'LONG_MIN'),
-    # Standard C variables
-    ('c:data', 'errno'),
-    # Standard environment variables
-    ('envvar', 'BROWSER'),
-    ('envvar', 'COLUMNS'),
-    ('envvar', 'COMSPEC'),
-    ('envvar', 'DISPLAY'),
-    ('envvar', 'HOME'),
-    ('envvar', 'HOMEDRIVE'),
-    ('envvar', 'HOMEPATH'),
-    ('envvar', 'IDLESTARTUP'),
-    ('envvar', 'LANG'),
-    ('envvar', 'LANGUAGE'),
-    ('envvar', 'LC_ALL'),
-    ('envvar', 'LC_CTYPE'),
-    ('envvar', 'LC_COLLATE'),
-    ('envvar', 'LC_MESSAGES'),
-    ('envvar', 'LC_MONETARY'),
-    ('envvar', 'LC_NUMERIC'),
-    ('envvar', 'LC_TIME'),
-    ('envvar', 'LINES'),
-    ('envvar', 'LOGNAME'),
-    ('envvar', 'PAGER'),
-    ('envvar', 'PATH'),
-    ('envvar', 'PATHEXT'),
-    ('envvar', 'SOURCE_DATE_EPOCH'),
-    ('envvar', 'TEMP'),
-    ('envvar', 'TERM'),
-    ('envvar', 'TMP'),
-    ('envvar', 'TMPDIR'),
-    ('envvar', 'TZ'),
-    ('envvar', 'USER'),
-    ('envvar', 'USERNAME'),
-    ('envvar', 'USERPROFILE'),
+def get_nitpick_ignore():
+    with open('nitpick_ignore.yml', encoding="utf-8") as fp:
+        ignore = yaml.safe_load(fp)
+
+    nitpick_ignore = []
+    for name in ignore['functions']:
+        nitpick_ignore.append(('c:func', name))
+    for name in ignore['types']:
+        nitpick_ignore.append(('c:type', name))
+        # Accept also standard types in ".. c:function::" definitions
+        nitpick_ignore.append(('c:identifier', name))
+    for name in ignore['macros']:
+        nitpick_ignore.append(('c:macro', name))
+    for name in ignore['variables']:
+        nitpick_ignore.append(('c:data', name))
+    for name in ignore['envvars']:
+        nitpick_ignore.append(('envvar', name))
+    return nitpick_ignore
+
+nitpick_ignore = get_nitpick_ignore()
+nitpick_ignore.append(
     # Do not error nit-picky mode builds when _SubParsersAction.add_parser cannot
     # be resolved, as the method is currently undocumented. For context, see
     # https://github.com/python/cpython/pull/103289.
-    ('py:meth', '_SubParsersAction.add_parser'),
-]
+    ('py:meth', '_SubParsersAction.add_parser')
+)
 
 # Disable Docutils smartquotes for several translations
 smartquotes_excludes = {

diff --git a/Doc/nitpick_ignore.yml b/Doc/nitpick_ignore.yml
@@ -0,0 +1,81 @@
+# nitpick_ignore of Sphinx conf.py
+
+# Standard C functions
+functions:
+  - calloc
+  - dlopen
+  - exec
+  - fcntl
+  - fork
+  - free
+  - gmtime
+  - localtime
+  - main
+  - malloc
+  - printf
+  - realloc
+  - snprintf
+  - sprintf
+  - stat
+  - system
+  - vsnprintf
+
+# Standard C types
+types:
+  - FILE
+  - __int
+  - intmax_t
+  - off_t
+  - ptrdiff_t
+  - siginfo_t
+  - size_t
+  - ssize_t
+  - time_t
+  - uintmax_t
+  - va_list
+  - wchar_t
+
+# Standard C macros
+macros:
+  - LLONG_MAX
+  - LLONG_MIN
+  - LONG_MAX
+  - LONG_MIN
+
+# Standard C variables
+variables:
+  - errno
+
+# Standard environment variables
+envvars:
+  - BROWSER
+  - COLUMNS
+  - COMSPEC
+  - DISPLAY
+  - HOME
+  - HOMEDRIVE
+  - HOMEPATH
+  - IDLESTARTUP
+  - LANG
+  - LANGUAGE
+  - LC_ALL
+  - LC_COLLATE
+  - LC_CTYPE
+  - LC_MESSAGES
+  - LC_MONETARY
+  - LC_NUMERIC
+  - LC_TIME
+  - LINES
+  - LOGNAME
+  - PAGER
+  - PATH
+  - PATHEXT
+  - SOURCE_DATE_EPOCH
+  - TEMP
+  - TERM
+  - TMP
+  - TMPDIR
+  - TZ
+  - USER
+  - USERNAME
+  - USERPROFILE
diff --git a/Doc/requirements.txt b/Doc/requirements.txt
@@ -17,4 +17,7 @@ sphinxext-opengraph==0.7.5
 # to install that as well.
 python-docs-theme>=2022.1
 
+# Parse Doc/nitpick_ignore.yml
+PyYAML
+
 -c constraints.txt
diff --git a/Doc/tools/.nitignore b/Doc/tools/.nitignore
@@ -8,7 +8,6 @@ Doc/c-api/arg.rst
 Doc/c-api/bool.rst
 Doc/c-api/buffer.rst
 Doc/c-api/bytes.rst
-Doc/c-api/call.rst
 Doc/c-api/capsule.rst
 Doc/c-api/cell.rst
 Doc/c-api/code.rst
@@ -26,8 +25,6 @@ Doc/c-api/init.rst
 Doc/c-api/init_config.rst
 Doc/c-api/intro.rst
 Doc/c-api/iterator.rst
-Doc/c-api/long.rst
-Doc/c-api/marshal.rst
 Doc/c-api/memory.rst
 Doc/c-api/memoryview.rst
 Doc/c-api/module.rst