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. Update Doc/requirements-oldest-sphinx.txt.
vstinner · Jul 25, 2023 · 3f82400 · 3f82400
1 parent 33838fe
commit 3f82400
Show file tree

Hide file tree

Showing 5 changed files with 115 additions and 82 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-oldest-sphinx.txt b/Doc/requirements-oldest-sphinx.txt
@@ -7,32 +7,32 @@ blurb
 python-docs-theme>=2022.1
 
 # Generated from:
-#     pip install "Sphinx~=3.2.0" "docutils<0.17" "Jinja2<3" "MarkupSafe<2"
+#     pip install "Sphinx~=3.2.0" "docutils<0.17" "Jinja2<3" "MarkupSafe<2" "PyYAML"
 #     pip freeze
 #
 # Sphinx 3.2 comes from ``needs_sphinx = '3.2'`` in ``Doc/conf.py``.
 # Docutils<0.17, Jinja2<3, and MarkupSafe<2 are additionally specified as
 # Sphinx 3.2 is incompatible with newer releases of these packages.
 
-Sphinx==3.2.1
 alabaster==0.7.13
 Babel==2.12.1
-certifi==2022.12.7
-charset-normalizer==3.1.0
-colorama==0.4.6
+certifi==2023.7.22
+charset-normalizer==3.2.0
 docutils==0.16
 idna==3.4
 imagesize==1.4.1
 Jinja2==2.11.3
 MarkupSafe==1.1.1
 packaging==23.1
 Pygments==2.15.1
+PyYAML==6.0.1
 requests==2.31.0
 snowballstemmer==2.2.0
+Sphinx==3.2.1
 sphinxcontrib-applehelp==1.0.4
 sphinxcontrib-devhelp==1.0.2
 sphinxcontrib-htmlhelp==2.0.1
 sphinxcontrib-jsmath==1.0.1
 sphinxcontrib-qthelp==1.0.3
 sphinxcontrib-serializinghtml==1.1.5
-urllib3==1.26.15
+urllib3==2.0.4
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