8000 gh-106948: Add Doc/nitpick_ignore.yml config file · python/cpython@3f82400 · GitHub
[go: up one dir, main page]
Skip to content

Commit 3f82400

Browse files
vstinnervstinner
committed
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.
1 parent 33838fe commit 3f82400

File tree

5 files changed

+115
-82
lines changed

5 files changed

+115
-82
lines changed

‎Doc/conf.py

Lines changed: 25 additions & 73 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,8 @@
1010
sys.path.append(os.path.abspath('tools/extensions'))
1111
sys.path.append(os.path.abspath('includes'))
1212

13+
import yaml
14+
1315
# General configuration
1416
# ---------------------
1517

@@ -76,82 +78,32 @@
7678
if venvdir is not None:
7779
exclude_patterns.append(venvdir + '/*')
7880

79-
nitpick_ignore = [
80-
# Standard C functions
81-
('c:func', 'calloc'),
82-
('c:func', 'dlopen'),
83-
('c:func', 'exec'),
84-
('c:func', 'fcntl'),
85-
('c:func', 'fork'),
86-
('c:func', 'free'),
87-
('c:func', 'gmtime'),
88-
('c:func', 'localtime'),
89-
('c:func', 'main'),
90-
('c:func', 'malloc'),
91-
('c:func', 'printf'),
92-
('c:func', 'realloc'),
93-
('c:func', 'snprintf'),
94-
('c:func', 'sprintf'),
95-
('c:func', 'stat'),
96-
('c:func', 'system'),
97-
('c:func', 'vsnprintf'),
98-
# Standard C types
99-
('c:type', 'FILE'),
100-
('c:type', '__int'),
101-
('c:type', 'intmax_t'),
102-
('c:type', 'off_t'),
103-
('c:type', 'ptrdiff_t'),
104-
('c:type', 'siginfo_t'),
105-
('c:type', 'size_t'),
106-
('c:type', 'ssize_t'),
107-
('c:type', 'time_t'),
108-
('c:type', 'uintmax_t'),
109-
('c:type', 'va_list'),
110-
('c:type', 'wchar_t'),
111-
# Standard C macros
112-
('c:macro', 'LLONG_MAX'),
113-
('c:macro', 'LLONG_MIN'),
114-
('c:macro', 'LONG_MAX'),
115-
('c:macro', 'LONG_MIN'),
116-
# Standard C variables
117-
('c:data', 'errno'),
118-
# Standard environment variables
119-
('envvar', 'BROWSER'),
120-
('envvar', 'COLUMNS'),
121-
('envvar', 'COMSPEC'),
122-
('envvar', 'DISPLAY'),
123-
('envvar', 'HOME'),
124-
('envvar', 'HOMEDRIVE'),
125-
('envvar', 'HOMEPATH'),
126-
('envvar', 'IDLESTARTUP'),
127-
('envvar', 'LANG'),
128-
('envvar', 'LANGUAGE'),
129-
('envvar', 'LC_ALL'),
130-
('envvar', 'LC_CTYPE'),
131-
('envvar', 'LC_COLLATE'),
132-
('envvar', 'LC_MESSAGES'),
133-
('envvar', 'LC_MONETARY'),
134-
('envvar', 'LC_NUMERIC'),
135-
('envvar', 'LC_TIME'),
136-
('envvar', 'LINES'),
137-
('envvar', 'LOGNAME'),
138-
('envvar', 'PAGER'),
139-
('envvar', 'PATH'),
140-
('envvar', 'PATHEXT'),
141-
('envvar', 'SOURCE_DATE_EPOCH'),
142-
('envvar', 'TEMP'),
143-
('envvar', 'TERM'),
144-
('envvar', 'TMP'),
145-
('envvar', 'TMPDIR'),
146-
('envvar', 'TZ'),
147-
('envvar', 'USER'),
148-
('envvar', 'USERNAME'),
149-
('envvar', 'USERPROFILE'),
81+
def get_nitpick_ignore():
82+
with open('nitpick_ignore.yml', encoding="utf-8") as fp:
83+
ignore = yaml.safe_load(fp)
84+
85+
nitpick_ignore = []
86+
for name in ignore['functions']:
87+
nitpick_ignore.append(('c:func', name))
88+
for name in ignore['types']:
89+
nitpick_ignore.append(('c:type', name))
90+
# Accept also standard types in ".. c:function::" definitions
91+
nitpick_ignore.append(('c:identifier', name))
92+
for name in ignore['macros']:
93+
nitpick_ignore.append(('c:macro', name))
94+
for name in ignore['variables']:
95+
nitpick_ignore.append(('c:data', name))
96+
for name in ignore['envvars']:
97+
nitpick_ignore.append(('envvar', name))
98+
return nitpick_ignore
99+
100+
nitpick_ignore = get_nitpick_ignore()
101+
nitpick_ignore.append(
150102
# Do not error nit-picky mode builds when _SubParsersAction.add_parser cannot
151103
# be resolved, as the method is currently undocumented. For context, see
152104
# https://github.com/python/cpython/pull/103289.
153-
('py:meth', '_SubParsersAction.add_parser'),
154-
]
105+
('py:meth', '_SubParsersAction.add_parser')
106+
)
155107

156108
# Disable Docutils smartquotes for several translations
157109
smartquotes_excludes = {

‎Doc/nitpick_ignore.yml

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
# nitpick_ignore of Sphinx conf.py
2+
3+
# Standard C functions
4+
functions:
5+
- calloc
6+
- dlopen
7+
- exec
8+
- fcntl
9+
- fork
10+
- free
11+
- gmtime
12+
- localtime
13+
- main
14+
- malloc
15+
- printf
16+
- realloc
17+
- snprintf
18+
- sprintf
19+
- stat
20+
- system
21+
- vsnprintf
22+
23+
# Standard C types
24+
types:
25+
- FILE
26+
- __int
27+
- intmax_t
28+
- off_t
29+
- ptrdiff_t
30+
- siginfo_t
31+
- size_t
32+
- ssize_t
33+
- time_t
34+
- uintmax_t
35+
- va_list
36+
- wchar_t
37+
38+
# Standard C macros
39+
macros:
40+
- LLONG_MAX
41+
- LLONG_MIN
42+
- LONG_MAX
43+
- LONG_MIN
44+
45+
# Standard C variables
46+
variables:
47+
- errno
48+
49+
# Standard environment variables
50+
envvars:
51+
- BROWSER
52+
- COLUMNS
53+
- COMSPEC
54+
- DISPLAY
55+
- HOME
56+
- HOMEDRIVE
57+
- HOMEPATH
58+
- IDLESTARTUP
59+
- LANG
60+
- LANGUAGE
61+
- LC_ALL
62+
- LC_COLLATE
63+
- LC_CTYPE
64+
- LC_MESSAGES
65+
- LC_MONETARY
66+
- LC_NUMERIC
67+
- LC_TIME
68+
- LINES
69+
- LOGNAME
70+
- PAGER
71+
- PATH
72+
- PATHEXT
73+
- SOURCE_DATE_EPOCH
74+
- TEMP
75+
- TERM
76+
- TMP
77+
- TMPDIR
78+
- TZ
79+
- USER
80+
- USERNAME
81+
- USERPROFILE

‎Doc/requirements-oldest-sphinx.txt

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -7,32 +7,32 @@ blurb
77
python-docs-theme>=2022.1
88

99
# Generated from:
10-
# pip install "Sphinx~=3.2.0" "docutils<0.17" "Jinja2<3" "MarkupSafe<2"
10+
# pip install "Sphinx~=3.2.0" "docutils<0.17" "Jinja2<3" "MarkupSafe<2" "PyYAML"
1111
# pip freeze
1212
#
1313
# Sphinx 3.2 comes from ``needs_sphinx = '3.2'`` in ``Doc/conf.py``.
1414
# Docutils<0.17, Jinja2<3, and MarkupSafe<2 are additionally specified as
1515
# Sphinx 3.2 is incompatible with newer releases of these packages.
1616

17-
Sphinx==3.2.1
1817
alabaster==0.7.13
1918
Babel==2.12.1
20-
certifi==2022.12.7
21-
charset-normalizer==3.1.0
22-
colorama==0.4.6
19+
certifi==2023.7.22
20+
charset-normalizer==3.2.0
2321
docutils==0.16
2422
idna==3.4
2523
imagesize==1.4.1
2624
Jinja2==2.11.3
2725
MarkupSafe==1.1.1
2826
packaging==23.1
2927
Pygments==2.15.1
28+
PyYAML==6.0.1
3029
requests==2.31.0
3130
snowballstemmer==2.2.0
31+
Sphinx==3.2.1
3232
sphinxcontrib-applehelp==1.0.4
3333
sphinxcontrib-devhelp==1.0.2
3434
sphinxcontrib-htmlhelp==2.0.1
3535
sphinxcontrib-jsmath==1.0.1
3636
sphinxcontrib-qthelp==1.0.3
3737
sphinxcontrib-serializinghtml==1.1.5
38-
urllib3==1.26.15
38+
urllib3==2.0.4

‎Doc/requirements.txt

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,4 +17,7 @@ sphinxext-opengraph==0.7.5
1717
# to install that as well.
1818
python-docs-theme>=2022.1
1919

20+
# Parse Doc/nitpick_ignore.yml
21+
PyYAML
22+
2023
-c constraints.txt

‎Doc/tools/.nitignore

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,6 @@ Doc/c-api/arg.rst
88
Doc/c-api/bool.rst
99
Doc/c-api/buffer.rst
1010
Doc/c-api/bytes.rst
11-
Doc/c-api/call.rst
1211
Doc/c-api/capsule.rst
1312
Doc/c-api/cell.rst
1413
Doc/c-api/code.rst
@@ -26,8 +25,6 @@ Doc/c-api/init.rst
2625
Doc/c-api/init_config.rst
2726
Doc/c-api/intro.rst
2827
Doc/c-api/iterator.rst
29-
Doc/c-api/long.rst
30-
Doc/c-api/marshal.rst
3128
Doc/c-api/memory.rst
3229
Doc/c-api/memoryview.rst
3330
Doc/c-api/module.rst

0 commit comments

Comments
 (0)
0