Skip to content

Commit b41831d

Browse files
fufu0615fufu0615
authored
Fix ci parameter checking script (#6864)
* 完善提取intitle参数的代码 * 添加更详细的文档参数检查日志 * 修复现有问题文档 * 统一用Inplace文档链接Outplace文档 * 总览和Inplace文档跳过参数检查 * 开启参数检查功能 * 部分勘误
1 parent 5f84cb0 commit b41831d

36 files changed

+188
-152
lines changed

‎ci_scripts/check_api_parameters.py

+84-27
Original file line numberDiff line numberDiff line change
@@ -56,76 +56,128 @@ def parse_args():
5656

5757
def _check_params_in_description(rstfilename, paramstr):
5858
flag = True
59-
params_intitle = []
59+
info = ""
60+
params_in_title = []
6061
if paramstr:
6162
fake_func = ast.parse(f"def fake_func({paramstr}): pass")
62-
for arg in fake_func.body[0].args.args:
63-
params_intitle.append(arg.arg)
63+
# Iterate over all in_title parameters
64+
num_defaults = len(fake_func.body[0].args.defaults)
65+
num_args = len(fake_func.body[0].args.args)
66+
# args & defaults
67+
for i, arg in enumerate(fake_func.body[0].args.args):
68+
if i >= num_args - num_defaults:
69+
default_value = fake_func.body[0].args.defaults[
70+
i - (num_args - num_defaults)
71+
]
72+
params_in_title.append(f"{arg.arg}={default_value}")
73+
else:
74+
params_in_title.append(arg.arg)
75+
# posonlyargs
76+
for arg in fake_func.body[0].args.posonlyargs:
77+
params_in_title.append(arg.arg)
78+
# vararg(*args)
79+
if fake_func.body[0].args.vararg:
80+
params_in_title.append(fake_func.body[0].args.vararg.arg)
81+
# kwonlyargs & kw_defaults
82+
for i, arg in enumerate(fake_func.body[0].args.kwonlyargs):
83+
if (
84+
i < len(fake_func.body[0].args.kw_defaults)
85+
and fake_func.body[0].args.kw_defaults[i] is not None
86+
):
87+
default_value = fake_func.body[0].args.kw_defaults[i]
88+
params_in_title.append(f"{arg.arg}={default_value}")
89+
else:
90+
params_in_title.append(arg.arg)
91+
# **kwargs
92+
if fake_func.body[0].args.kwarg:
93+
params_in_title.append(fake_func.body[0].args.kwarg.arg)
6494

6595
funcdescnode = extract_params_desc_from_rst_file(rstfilename)
6696
if funcdescnode:
6797
items = funcdescnode.children[1].children[0].children
68-
if len(items) != len(params_intitle):
98+
list_pat = r"^<list_item>.*</list_item>$"
99+
if not re.match(list_pat, str(items[0])):
69100
flag = False
101+
info = "Something wrong with the format of params list in description, check it please."
102+
elif len(items) != len(params_in_title):
103+
flag = False
104+
if not items:
105+
info = (
106+
"Params section in description is empty, check it please."
107+
)
108+
else:
109+
info = f"The number of params in title does not match the params in description: {len(params_in_title)} != {len(items)}."
70110
print(f"check failed (parammeters description): {rstfilename}")
71111
else:
72112
for i in range(len(items)):
73-
pname_intitle = params_intitle[i].split("=")[0].strip()
74-
mo = re.match(r"(\w+)\b.*", items[i].children[0].astext())
113+
pname_in_title = params_in_title[i].split("=")[0].strip()
114+
mo = re.match(
115+
r"\*{0,2}(\w+)\b.*", items[i].children[0].astext()
116+
)
75117
if mo:
76118
pname_indesc = mo.group(1)
77-
if pname_indesc != pname_intitle:
119+
if pname_indesc != pname_in_title:
78120
flag = False
121+
info = f"the following param in title does not match the param in description: {pname_in_title} != {pname_indesc}."
79122
print(
80-
f"check failed (parammeters description): {rstfilename}, {pname_indesc} != {pname_intitle}"
123+
f"check failed (parammeters description): {rstfilename}, {pname_in_title} != {pname_indesc}"
81124
)
82125
else:
83126
flag = False
127+
info = f"param name '{pname_in_title}' not matched in description line{i+1}, check it please."
84128
print(
85129
f"check failed (parammeters description): {rstfilename}, param name not found in {i} paragraph."
86130
)
87131
else:
88-
if params_intitle:
132+
if params_in_title:
133+
info = "params section not found in description, check it please."
89134
print(
90-
f"check failed (parameters description not found): {rstfilename}, {params_intitle}."
135+
f"check failed (parameters description not found): {rstfilename}, {params_in_title}."
91136
)
92137
flag = False
93-
return flag
138+
return flag, info
94139

95140

96141
def _check_params_in_description_with_fullargspec(rstfilename, funcname):
97142
flag = True
143+
info = ""
98144
funcspec = inspect.getfullargspec(eval(funcname))
99145
funcdescnode = extract_params_desc_from_rst_file(rstfilename)
100146
if funcdescnode:
101147
items = funcdescnode.children[1].children[0].children
102148
params_inspec = funcspec.args
103149
if len(items) != len(params_inspec):
104150
flag = False
151+
info = f"check_with_fullargspec failed (parammeters description): {rstfilename}"
105152
print(f"check failed (parammeters description): {rstfilename}")
106153
else:
107154
for i in range(len(items)):
108-
pname_intitle = params_inspec[i]
109-
mo = re.match(r"(\w+)\b.*", items[i].children[0].astext())
155+
pname_in_title = params_inspec[i]
156+
mo = re.match(
157+
r"\*{0,2}(\w+)\b.*", items[i].children[0].astext()
158+
)
110159
if mo:
111160
pname_indesc = mo.group(1)
112-
if pname_indesc != pname_intitle:
161+
if pname_indesc != pname_in_title:
113162
flag = False
163+
info = f"the following param in title does not match the param in description: {pname_in_title} != {pname_indesc}."
114164
print(
115-
f"check failed (parammeters description): {rstfilename}, {pname_indesc} != {pname_intitle}"
165+
f"check failed (parammeters description): {rstfilename}, {pname_in_title} != {pname_indesc}"
116166
)
117167
else:
118168
flag = False
169+
info = f"param name '{pname_in_title}' not matched in description line{i+1}, check it please."
119170
print(
120171
f"check failed (parammeters description): {rstfilename}, param name not found in {i} paragraph."
121172
)
122173
else:
123174
if funcspec.args:
175+
info = "params section not found in description, check it please."
124176
print(
125177
f"check failed (parameters description not found): {rstfilename}, {funcspec.args}."
126178
)
127179
flag = False
128-
return flag
180+
return flag, info
129181

130182

131183
def check_api_parameters(rstfiles, apiinfo):
@@ -138,11 +190,11 @@ def check_api_parameters(rstfiles, apiinfo):
138190
2. Some COMPLICATED annotations may break the scripts.
139191
"""
140192
pat = re.compile(
141-
r"^\.\.\s+py:(method|function|class)::\s+(\S+)\s*\(\s*(.*)\s*\)\s*$"
193+
r"^\.\.\s+py:(method|function|class)::\s+([^\s(]+)\s*(?:\(\s*(.*)\s*\))?\s*$"
142194
)
143195
check_passed = []
144-
check_failed = []
145-
api_notfound = []
196+
check_failed = {}
197+
api_notfound = {}
146198
for rstfile in rstfiles:
147199
rstfilename = osp.join("../docs", rstfile)
148200
print(f"checking : {rstfile}")
@@ -171,22 +223,24 @@ def check_api_parameters(rstfiles, apiinfo):
171223
print(
172224
f"check func:{funcname} in {rstfilename} with {paramstr}"
173225
)
174-
flag = _check_params_in_description(
226+
flag, info = _check_params_in_description(
175227
rstfilename, paramstr
176228
)
177229
else:
178230
print(
179231
f'check func:{funcname} in {rstfilename} with {paramstr}, but different with json\'s {apiobj["args"]}'
180232
)
181-
flag = _check_params_in_description(
233+
flag, info = _check_params_in_description(
182234
rstfilename, paramstr
183235
)
184236
else: # paddle.abs class_method does not have `args` in its json item.
185237
print(
186238
f"check func:{funcname} in {rstfilename} with its FullArgSpec"
187239
)
188-
flag = _check_params_in_description_with_fullargspec(
189-
rstfilename, funcname
240+
flag, info = (
241+
_check_params_in_description_with_fullargspec(
242+
rstfilename, funcname
243+
)
190244
)
191245
break
192246
if not func_found_in_json: # may be inner functions
@@ -200,11 +254,12 @@ def check_api_parameters(rstfiles, apiinfo):
200254
check_passed.append(rstfile)
201255
print(f"check success: {rstfile}")
202256
else:
203-
check_failed.append(rstfile)
257+
check_failed[rstfile] = info
204258
print(f"check failed: {rstfile}")
205259
break
206260
if not func_found:
207-
api_notfound.append(rstfile)
261+
info = 'funcname in title is not found, please check the format of ".. py:function::func()"'
262+
api_notfound[rstfile] = info
208263
print(f"check failed (object not found): {rstfile}")
209264
print(f"checking done: {rstfile}")
210265
return check_passed, check_failed, api_notfound
@@ -220,9 +275,11 @@ def check_api_parameters(rstfiles, apiinfo):
220275
result = True
221276
if check_failed:
222277
result = False
223-
print(f"check_api_parameters failed: {check_failed}")
278+
for path, info in check_failed.items():
279+
print(f"Checking failed file:{path}\nError:{info}\n")
224280
if api_notfound:
225-
print(f"check_api_parameters funcname not found in: {api_notfound}")
281+
for path, info in api_notfound.items():
282+
print(f"Checking failed file:{path}\nError:{info}\n")
226283
if result:
227284
sys.exit(0)
228285
else:

‎ci_scripts/check_api_parameters.sh

+3
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,9 @@ function filter_cn_api_files() {
1111
local __resultvar=$2
1212
local need_check_files=""
1313
for file in `echo $git_files`;do
14+
if [[ "$file" == *"Overview_cn.rst"* ]] || [[ "$file" == *__cn.rst ]]; then
15+
continue
16+
fi
1417
echo "$file" | grep '.*\.rst$' > /dev/null
1518
if [ $? -eq 0 ] ;then
1619
need_check_files="${need_check_files} $file"

‎ci_scripts/ci_start.sh

+1-1
Original file line numberDiff line numberDiff line change
@@ -83,7 +83,7 @@ if [ "${BUILD_DOC}" = "true" ] && [ -x /usr/local/bin/sphinx-build ] ; then
8383
fi
8484
fi
8585

86-
check_parameters=OFF
86+
check_parameters=ON
8787
if [ "${check_parameters}" = "OFF" ] ; then
8888
#echo "chinese api doc fileslist is empty, skip check."
8989
echo "check_api_parameters is not stable, close it temporarily."

‎docs/api/paddle/atan2_cn.rst

+3-3
Original file line numberDiff line numberDiff line change
@@ -23,9 +23,9 @@ atan2
2323
参数
2424
:::::::::
2525

26-
- **x** (Tensor) - 输入的 Tensor，数据类型为：int32、int64、float16、float32、float64。
27-
- **y** (Tensor) - 输入的 Tensor，数据类型为：int32、int64、float16、float32、float64。
28-
- **name** (str，可选) - 操作的名称（可选，默认值为 None）。更多信息请参见 :ref:`api_guide_Name`。
26+
- **x** (Tensor) - 输入的 Tensor，数据类型为：int32、int64、float16、float32、float64。
27+
- **y** (Tensor) - 输入的 Tensor，数据类型为：int32、int64、float16、float32、float64。
28+
- **name** (str，可选) - 操作的名称（可选，默认值为 None）。更多信息请参见 :ref:`api_guide_Name`。
2929

3030
返回
3131
:::::::::

‎docs/api/paddle/bitwise_and_cn.rst

+1
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@ bitwise_and
2020
- **x** （Tensor）- 输入的 N-D `Tensor`，数据类型为：bool，uint8，int8，int16，int32，int64。
2121
- **y** （Tensor）- 输入的 N-D `Tensor`，数据类型为：bool，uint8，int8，int16，int32，int64。
2222
- **out** （Tensor，可选）- 输出的结果 `Tensor`，是与输入数据类型相同的 N-D `Tensor`。默认值为 None，此时将创建新的 Tensor 来保存输出结果。
23+
- **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。
2324

2425
返回
2526
::::::::::::

‎docs/api/paddle/bitwise_not_cn.rst

+1
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@ bitwise_not
2020

2121
- **x** （Tensor）- 输入的 N-D `Tensor`，数据类型为：bool，uint8，int8，int16，int32，int64。
2222
- **out** （Tensor，可选）- 输出的结果 `Tensor`，是与输入数据类型相同的 N-D `Tensor`。默认值为 None，此时将创建新的 Tensor 来保存输出结果。
23+
- **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。
2324

2425
返回
2526
::::::::::::

‎docs/api/paddle/bitwise_or_cn.rst

+1
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,7 @@ bitwise_or
2121
- **x** （Tensor）- 输入的 N-D `Tensor`，数据类型为：bool，uint8，int8，int16，int32，int64。
2222
- **y** （Tensor）- 输入的 N-D `Tensor`，数据类型为：bool，uint8，int8，int16，int32，int64。
2323
- **out** （Tensor，可选）- 输出的结果 `Tensor`，是与输入数据类型相同的 N-D `Tensor`。默认值为 None，此时将创建新的 Tensor 来保存输出结果。
24+
- **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。
2425

2526
返回
2627
::::::::::::

‎docs/api/paddle/bitwise_xor_cn.rst

+1
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,7 @@ bitwise_xor
2121
- **x** （Tensor）- 输入的 N-D `Tensor`，数据类型为：bool，uint8，int8，int16，int32，int64。
2222
- **y** （Tensor）- 输入的 N-D `Tensor`，数据类型为：bool，uint8，int8，int16，int32，int64。
2323
- **out** （Tensor，可选）- 输出的结果 `Tensor`，是与输入数据类型相同的 N-D `Tensor`。默认值为 None，此时将创建新的 Tensor 来保存输出结果。
24+
- **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。
2425

2526
返回
2627
::::::::::::

‎docs/api/paddle/deg2rad_cn.rst

+2-2
Original file line numberDiff line numberDiff line change
@@ -14,8 +14,8 @@ deg2rad
1414
参数
1515
:::::::::
1616

17-
- **x** (Tensor) - 输入的 Tensor，数据类型为：int32、int64、float32、float64。
18-
- **name** (str，可选) - 操作的名称（可选，默认值为 None）。更多信息请参见 :ref:`api_guide_Name`。
17+
- **x** (Tensor) - 输入的 Tensor，数据类型为：int32、int64、float32、float64。
18+
- **name** (str，可选) - 操作的名称（可选，默认值为 None）。更多信息请参见 :ref:`api_guide_Name`。
1919

2020
返回
2121
:::::::::

‎docs/api/paddle/einsum_cn.rst

+2-5
Original file line numberDiff line numberDiff line change
@@ -67,15 +67,12 @@ Einsum 求和过程理论上等价于如下四步，但实现中实际执行的
6767
参数
6868
:::::
6969

70-
71-
**equation** (str)：求和标记
72-
73-
**operands** (Tensor, [Tensor, ...])：输入 Tensor
70+
- **equation** (str)：求和标记
71+
- **operands** (Tensor, [Tensor, ...])：输入 Tensor
7472

7573
返回
7674
:::::
7775

78-
7976
Tensor：输出 Tensor
8077

8178
代码示例

‎docs/api/paddle/erfinv_cn.rst

+2-2
Original file line numberDiff line numberDiff line change
@@ -13,8 +13,8 @@ erfinv
1313
参数
1414
:::::::::
1515

16-
- **x** (Tensor) - 输入的 Tensor，数据类型为：float16、bfloat16、float32、float64。
17-
- **name** (str，可选) - 操作的名称（可选，默认值为 None）。更多信息请参见 :ref:`api_guide_Name`。
16+
- **x** (Tensor) - 输入的 Tensor，数据类型为：float16、bfloat16、float32、float64。
17+
- **name** (str，可选) - 操作的名称（可选，默认值为 None）。更多信息请参见 :ref:`api_guide_Name`。
1818

1919
返回
2020
:::::::::

‎docs/api/paddle/expm1_cn.rst

+2-2
Original file line numberDiff line numberDiff line change
@@ -16,8 +16,8 @@ expm1
1616
参数
1717
:::::::::
1818

19-
- **x** (Tensor) - 该 OP 的输入为多维 Tensor。数据类型为：int32、int64、float16、float32、float64、complex64、complex128。
20-
- **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。
19+
- **x** (Tensor) - 该 OP 的输入为多维 Tensor。数据类型为：int32、int64、float16、float32、float64、complex64、complex128。
20+
- **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。
2121

2222
返回
2323
:::::::::

‎docs/api/paddle/gcd_cn.rst

+3-3
Original file line numberDiff line numberDiff line change
@@ -19,9 +19,9 @@ gcd
1919
参数
2020
:::::::::
2121

22-
- **x** (Tensor) - 输入的 Tensor，数据类型为：int32，int64。
23-
- **y** (Tensor) - 输入的 Tensor，数据类型为：int32，int64。
24-
- **name** (str，可选) - 操作的名称（可选，默认值为 None）。更多信息请参见 :ref:`api_guide_Name`。
22+
- **x** (Tensor) - 输入的 Tensor，数据类型为：int32，int64。
23+
- **y** (Tensor) - 输入的 Tensor，数据类型为：int32，int64。
24+
- **name** (str，可选) - 操作的名称（可选，默认值为 None）。更多信息请参见 :ref:`api_guide_Name`。
2525

2626
返回
2727
:::::::::

‎docs/api/paddle/get_cuda_rng_state_cn.rst

-6
Original file line numberDiff line numberDiff line change
@@ -6,12 +6,6 @@ get_cuda_rng_state
66
77
获取 cuda 随机数生成器的状态信息。
88

9-
10-
参数
11-
::::::::::::
12-
13-
无。
14-
159
返回
1610
::::::::::::
1711

‎docs/api/paddle/get_default_dtype_cn.rst

-7
Original file line numberDiff line numberDiff line change
@@ -8,13 +8,6 @@ get_default_dtype
88
99
得到当前全局的 dtype。该值初始是 float32。
1010

11-
12-
参数
13-
::::::::::::
14-
15-
16-
无
17-
1811
返回
1912
::::::::::::
2013
string，这个全局 dtype 仅支持 float16、float32、float64。

‎docs/api/paddle/histogramdd_cn.rst

+1-1
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ histogramdd
1313
参数
1414
::::::::::::
1515

16-
- **input** (Tensor) - 输入多维 Tensor 。
16+
- **x** (Tensor) - 输入多维 Tensor 。
1717
- **bins** (Tensor[]|int[]|int) - 如果为 Tensor 数组，则表示所有 bin 边界。如果为 int 数组，则表示每个维度中等宽 bin 的数量。如果为 int，则表示所有维度的等宽 bin 数量。默认值为 10 ，表示所有维度的等宽 bin 数量为 10 个。
1818
- **ranges** (float[], 可选) - 表示每个维度中最左边和最右边的 bin 边界。如果为 None ，则将每个尺寸的最小值和最大值设置为最左边和最右边。默认值为 None ，表示自动根据最大值与最小值计算 bin 的边界。
1919
- **density** (bool，可选) - 表示是否计算 density ，如果为 False，结果将包含每个 bin 中的计数（或权重）。如果为 True，则将每个计数（权重）除以总计数（总权重），然后再除以相关 bin 的宽度。默认值为 False ，表示不计算 density 。

0 commit comments

Comments
 (0)