【Docathon】 中文 api 文档中的 api_label 规范

[ooooo-create]

#6165

相关背景：

Paddle 框架下每个 API 文档都有对应的 api_label，其主要作用是用于文档间的相互引用（通过 ref：api_label 的形式）。其中，英文 API 文档的 api_label 是按照一定规则自动生成的，而中文 API 文档的 api_label 则是由人为定义的（即在 docs 仓库下每一个 API 对应的 .rst 文件中的首行）。
由于中文 API 文档的 api_label 没有一个标准的规范，导致开发者在引用某中文 API 文档时，不能直观地确定其 api_label 是什么，必须得先去找到对应的 .rst 文件查看才能知晓，没有规律可循，也不优雅。
因此，该活动旨在对中文 API 文档的 api_label 进行统一规范，让用户的开发体验更加丝滑。

规范要求

接下来说说我们定义的 api_label 规范

• en（英文）：利用 API 名称来辅助命名, <api_> + <把 API 的.替换成_> 之后的结果
  

  docs/docs/api/gen_doc.py

  Line 746 in 09e2032

  '_api_' + self.api_name.replace('.', '_') if self.api_name else None

• cn（中文）： cn_ + 英文 api label

举个例子：paddle.add

• 英文 api_label : api_paddle_add
• 中文 api_label : cn_api_paddle_add

在 .rst 文件中，我们需要满足的格式：.. _cn_api_paddle_add，也就是需要在开头添加.. _以及在末尾添加:，然后放在文件的第一行。（这不代表不会出现一个文件多个label的情况

现在的情况

1. 大量 api_label 是不符合上述规范的
2. 存在 api_label 是与 fluid 有关的
3. 发现有相当一部分的文档内容中包含对 fluid 文档的引用，我们需要对此进行处理。因为 fluidAPI 在 paddle2.5版本就已经被废弃了，相关 API 清理工作也已在进行，因此文档也要及时更新。
4. 中文文档 ci 检查中缺失对 api_label 检查

目标：

一、处理文件本身的 api_label 以及在此基础上的 ref: api_label 替换

一个 rst 文件对应于一个 API 的中文文档，用 rst 文件路径可以组成 API 名称

1. 通过遍历 api 目录下所有 .rst 文件（不包括 overview.rst 等和 API 本身无关的文件),获取文件路径。
2. 对每一个路径，将其转换成 api_label(new)
   例如：docs/docs/api/paddle/abs_cn.rst 路径转换成 cn_api_paddle_abs
3. 对每一个路径，获取当前文件的第一行，转换成 api_label(old)
   例如：docs/docs/api/paddle/abs_cn.rst 的第一行: .. _cn_api_fluid_layers_abs: 转换成 cn_api_fluid_layers_abs
4. 再次遍历（同 步骤1，但是仅仅是 .rst 文件的要求），将api_label(old) 替换成 api_label(new)，同时完成了 ref：api_label 的替换
   编写一个脚本即可完成 [automatic repair] update Chinese api_label with new standard #6171

二、处理上述方式所不能解决的问题

1. 之前引用的 api label 就是写错了，替换不成功。api_label 不是首行写的
   个数不多，单独处理即可 [automatic repair] update Chinese api_label with new standard #6171
2. （拆分任务）引用 fluid相关label 时，因为 fluid 目录下的 API 已经废弃所造成的无效引用
   这次任务的目的，就是把对 fluid 文档的引用进行修正。

• 1. 虽然之前 fluid 目录下的 API 已经废弃了，但是我们还有一些可以替代的 API ，可以初步参考 Paddle 1.8 与 Paddle 2.0 API 映射表
• 2. 对于不确定的api或者找不到对应的 API ，都可以在在此 issue下回复

例子

对于：cn_api_fluid_layers_concat

docs/docs/api_guides/low_level/layers/tensor.rst

Line 49 in eba6a1f

API reference 请参考：:ref:`cn_api_fluid_layers_concat`

按照 [api 名称] -> [英文 label] -> [中文 label] -> [rst 格式] ：paddle.concat -> api_paddle_conact -> cn_api_paddle_conact -> .. _cn_api_paddle_conact:
在任务一的基础上，我们只需要修改 ref 引用的 api_label 即可

三、中文文档 ci 检查 api_label 功能的添加

检查项有两个：一个是文件本身的 api_label 是否正确，一个是文件引用的 api_label 是否格式正确（是否存在

1. 使用目标一的方式，获取文件第一行的 api_label(old)，和通过文件路径转换的 api_label(new），相同即可
2. 在 进行 1 的时候，获取一个包含所有 api_label(new） 的列表
3. 遍历文件的 api_label 引用 ，引用在列表中存在即可
   [ci]修复中文 api_label 检查的若干问题 #6237 , [fix] fix argument bugs check_api_label_cn.py #6246 , [Docathon][CodeStyle Fix No.8] enable C403 rule  #6266

任务清单：

规则见目标二.2
在目标一，和目标二.1完成的情况下，通过遍历 API 文档的每一个文件里的每一个 ref 引用，并判断是否包含 fluid 得出需要人为验证和修正的引用 api_label ，具体如下。

序号	label name	出现次数	认领人	PR 链接
1	cn_api_fluid_ExecutionStrategy	1	@SigureMo	#6206 ✅
2	cn_api_fluid_ParallelExecutor	1	@SigureMo	#6206 ✅
3	api_fluid_LoDTensor	2	@SigureMo	#6206 ✅
4	cn_api_fluid_ParallelExecutor	1	@SigureMo	#6206 ✅
5	cn_api_fluid_layers_DynamicRNN	1	@ooooo-create	#6220✅
6	cn_api_fluid_layers_While	1	@ooooo-create	#6220 ✅
7	cn_api_fluid_layers_chunk_eval	2	@ooooo-create	#6220✅
8	cn_api_fluid_layers_concat	1	@ooooo-create	#6220✅
9	cn_api_fluid_layers_create_tensor	1	@ooooo-create	#6220✅
10	cn_api_fluid_layers_embedding	1	@ooooo-create	#6220✅
11	cn_api_fluid_layers_gather	1	@ooooo-create	#6220✅
12	cn_api_fluid_layers_linear_chain_crf	2	@ooooo-create	#6220 ✅
13	cn_api_fluid_layers_reverse	1	@ooooo-create	#6220✅
14	cn_api_fluid_layers_size	1	@ooooo-create	#6220✅
15	cn_api_fluid_layers_split	1	@ooooo-create	#6220✅
16	cn_api_fluid_layers_stack	1	@ooooo-create	#6220 ✅
17	cn_api_fluid_layers_strided_slice	1	@ooooo-create	#6220✅
18	cn_api_fluid_layers_topk	1	@ooooo-create	#6220 ✅
19	cn_api_fluid_layers_unique	1	@ooooo-create	#6220 ✅
20	cn_api_fluid_layers_unsqueeze	1	@ooooo-create	#6220 ✅
21	cn_api_fluid_regularizer_L1Decay	7	@ooooo-create	#6220✅
22	cn_api_fluid_regularizer_L2Decay	7	@ooooo-create	#6200 ✅
23	cn_api_fluid_profiler_cuda_profiler	1	@ooooo-create	#6220 ✅
24	cn_api_fluid_layers_create_parameter	1	@ooooo-create	#6220 ✅
25	cn_api_fluid_profiler_profiler	1	@ooooo-create	#6220 ✅
26	cn_api_fluid_require_version	1	@ooooo-create	#6220✅
27	cn_api_fluid_profiler_reset_profiler	1	@ooooo-create	#6220 ✅
28	cn_api_fluid_profiler_start_profiler	1	@ooooo-create	#6220 ✅
29	cn_api_fluid_profiler_stop_profiler	1	@ooooo-create	#6220 ✅

请认领以上 API Label 并进行修改。

任务流程

1. 请直接在 issue 区回复任务序号进行认领
2. 提交 PR 时，请注意 PR 描述的规范。
   a. PR 标题： [Docathon] Fix xxx API Label
   b. PR 内容： 描述修改的文件、附上该 issue 链接、 并 @ooooo-create
3. PR 合入后即完成任务啦～

PR的提交：

按照文档贡献指南的方式：按照文档贡献指南，