CI脚本检查api参数存在的问题

[fufu0615]

问题复现

本地进行文档 CI ，在 ci_start.sh 中运行检查 api 参数的脚本 check_api_parameters.sh ，对 ./docs/api/paddle 路径下的所有 *_cn.rst 文档进行检查。

使用脚本找到部分异常文档，异常文档主要分为两大类：

1. 输出异常信息： check_api_parameters_funcname_not_found ，一般是文档开头的api格式的问题，导致正则表达式无法获取到，也是脚本主要的问题所在。

   大致可以分为以下几类：

   • api不以括号结尾

   • api后有多余冒号

   • 为总览文档，开头无api

2. 输出异常信息： check_api_parameters_failed，一般是文档其他格式问题

   大致分为以下几类：

   • 文档参数模块缩进错误

   • api包含的可变参数*{}或**{}被忽略

   • 文档或api缺少name参数

   • api_info_all.json文件中没找到

   • api无参数，但文档写的“无”被当成一个参数

   • 文档参数名称和api不同

   • 文档缺少参数板块

   • 文档或api中缺少对某个参数的描述

   • 文档描述一个参数时换行

异常文档的具体名单

1. • api不以括号结尾

     "api/paddle/CPUPlace_cn.rst",
     "api/paddle/CUDAPinnedPlace_cn.rst",
     "api/paddle/CUDAPlace_cn.rst",
     "api/paddle/NPUPlace_cn.rst",
     "api/paddle/Tensor_cn.rst",

   • api后有多余冒号

     "api/paddle/pdist_cn.rst",
     "api/paddle/reduce_as_cn.rst",
     "api/paddle/rot90_cn.rst",

   • 为总览文档，开头无api

     "api/paddle/Overview_cn.rst"

2. check_api_parameters_failed，一般是文档其他格式问题

   大致分为以下几类：

   • 文档参数模块缩进错误

     "api/paddle/atan2_cn.rst",
     "api/paddle/deg2rad_cn.rst",
     "api/paddle/erfinv_cn.rst",
     "api/paddle/expm1_cn.rst",
     "api/paddle/gcd_cn.rst",
     "api/paddle/lcm_cn.rst",
     "api/paddle/lerp_cn.rst",
     "api/paddle/put_along_axis_cn.rst",
     "api/paddle/rad2deg_cn.rst",
     "api/paddle/renorm_cn.rst",
     "api/paddle/select_scatter_cn.rst",
     "api/paddle/take_along_axis_cn.rst",
     "api/paddle/take_cn.rst",

   • api包含的可变参数*{}或**{}被忽略

     "api/paddle/atleast_1d_cn.rst",
     "api/paddle/atleast_2d_cn.rst",
     "api/paddle/atleast_3d_cn.rst",
     "api/paddle/einsum_cn.rst",
     "api/paddle/load_cn.rst",
     "api/paddle/meshgrid_cn.rst",

   • 文档或api缺少name参数

     // 文档中缺少
     "api/paddle/bitwise_and_cn.rst",
     "api/paddle/bitwise_not_cn.rst",
     "api/paddle/bitwise_or_cn.rst",
     "api/paddle/bitwise_xor_cn.rst",
     
     // api中缺少
     "api/paddle/numel_cn.rst",

   • api_info_all.json文件中没找到

     "api/paddle/cartesian_prod_cn.rst",
     "api/paddle/log_normal_cn.rst",

   • api无参数，但文档写的“无”被当成一个参数

     "api/paddle/get_cuda_rng_state_cn.rst",
     "api/paddle/get_default_dtype_cn.rst",

   • 文档参数名称和api不同

     "api/paddle/histogramdd_cn.rst",

   • 文档缺少参数板块

     "api/paddle/index_fill_cn.rst",
     "api/paddle/index_put_cn.rst",

   • 文档或api中缺少对某个参数的描述

     "api/paddle/round_cn.rst",
     "api/paddle/save_cn.rst",

   • 文档描述一个参数时换行

     "api/paddle/unstack_cn.rst"

修复建议

1. 对于第一类异常文档，除总览文档 Overview_cn.rst 外，可通过修改 check_api_parameters.py 脚本中 141 行用于提取 api 的正则表达式来解决：

   # 修改前
   r"^\.\.\s+py:(method|function|class)::\s+(\S+)\s*\(\s*(.*)\s*\)\s*$"
   
   # 修改后
   r"^\.\.\s+py:(method|function|class)::\s+(\S+?)(?:\((.*?)\))?\s*:?\s*$"

2. 对于第二类异常文档，考虑到大多是在参数检查脚本被关闭后上传的，可能是因为缺少了参数检查这一步导致的文档格式不统一。

   • 计划先解决以下几类可以通过修正文档格式来处理的异常：

     • 文档参数模块缩进错误
     • 文档或api缺少name参数
     • 文档参数名称和api不同
     • 文档描述一个参数时换行

   • 对于下面这类异常，可以尝试完善 check_api_parameters.py 脚本中获取api参数的部分来解决：

     • api包含的可变参数*{}或**{}被忽略

   • 下面这类异常的解决方案，需要进一步查看 docs\api\copy_codes_from_en_doc.py 脚本来确定：

     • api_info_all.json文件中没找到

   • 剩下的三类异常则考虑确定一下这类文档的具体规范写法再解决：

     • api无参数，但文档写的“无”被当成一个参数
     • 文档缺少参数板块
     • 文档或api中缺少对某个参数的描述

[fufu0615]

尝试修复的pr：#6864