CI脚本检查api参数存在的问题 (original) (raw)

问题复现

本地进行文档 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中缺少对某个参数的描述
    • 文档描述一个参数时换行

异常文档的具体名单

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