From 3f82400041f80938f96b80cca549b55445f52f76 Mon Sep 17 00:00:00 2001 From: Victor Stinner Date: Wed, 26 Jul 2023 01:34:39 +0200 Subject: [PATCH] gh-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. --- Doc/conf.py | 98 ++++++++---------------------- Doc/nitpick_ignore.yml | 81 ++++++++++++++++++++++++ Doc/requirements-oldest-sphinx.txt | 12 ++-- Doc/requirements.txt | 3 + Doc/tools/.nitignore | 3 - 5 files changed, 115 insertions(+), 82 deletions(-) create mode 100644 Doc/nitpick_ignore.yml diff --git a/Doc/conf.py b/Doc/conf.py index 453f4fc63883ad..050bd70e6f1c29 100644 --- 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 new file mode 100644 index 00000000000000..250e4431a20207 --- /dev/null +++ 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 index f7e0665bde445d..b18aea84ce880d 100644 --- a/Doc/requirements-oldest-sphinx.txt +++ b/Doc/requirements-oldest-sphinx.txt @@ -7,19 +7,17 @@ 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 @@ -27,12 +25,14 @@ 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 index bde509febf5bde..e01771cd5d0e43 100644 --- 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 index fc6de10eb1c2c8..07123bcb5ae064 100644 --- 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