remove api_label

[SigureMo]

如 PaddlePaddle/Paddle#56682 所述，英文文档的 label 本就是自动生成的：

docs/docs/api/gen_doc.py

Line 746 in 09e2032

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

这里会生成一个新的 api_label，就是按照上述规则自动生成的，repo 里的这个没有任何地方会用到，而且会误导大家

已经搜索了下 repo 里的这个 api_label 中不规范的部分（即 'api_' + left.replace(".", "_") != right） 的，发现很少，只有一个 remainder_ 还没放在 paddle.__all__ 里无法预览，也在 PaddlePaddle/Paddle#56682 修了

另外中文的 api label 可太不规范了，引用 api 必须找那篇文档才知道，以后可以考虑出个小任务来规范一下

PADDLEPADDLE_PR=56682

[paddle-bot]

感谢你贡献飞桨文档，文档预览构建中，Docs-New 跑完后即可预览，预览链接：http://preview-pr-6142.paddle-docs-preview.paddlepaddle.org.cn/documentation/docs/zh/api/index_cn.html
预览工具的更多说明，请参考：飞桨文档预览工具

[sunzhongkai588]

LGTM～

[sunzhongkai588]

@SigureMo https://github.com/PaddlePaddle/docs/wiki/飞桨文档相互引用 这里面关于 api_label 的描述可能需要同步修改下

另外中文的 api label 可太不规范了，引用 api 必须找那篇文档才知道，以后可以考虑出个小任务来规范一下

关于中文 api label，有一下几点思考：

• 如果要便于查找的话，中文 api label 是否像以前的英文一样要维护一个 api_label 列表？（不过感觉维护成本比较大）
• 不维护的话，必须得找到中文文档下的第一行，如 .. _cn_api_amp_GradScaler:，确实也很麻烦。可行的方法就是我们先制定规范，比如就 _cn + 英文api label 。然后统一发几个任务：
  • 1. 找出 label 不规范的中文api （这个能通过自动脚本方式找么？）
  • 2. 修改 label
  • 3. 文档写作模板中针对 api_label 的规范增加相应描述

[SigureMo]

如果要便于查找的话，中文 api label 是否像以前的英文一样要维护一个 api_label 列表？（不过感觉维护成本比较大）

我觉得维护这个列表是不合适的，很容易造成不同步

找出 label 不规范的中文api （这个能通过自动脚本方式找么？）

可以的，首先遍历全部 API 文档，找出 label，即可根据「文件路径」->「API 名称」->「英文 label」->「中文 label」得到规范的 label，进而比对即可得知是否规范

修改 label

首先上面可以统计全部旧 label，并全文搜索旧 label 的引用，进行替换即可

此外，为了规范化，我们应当在中文 API 文档发生改动 / 添加时检查其 label 是否符合新规范

[sunzhongkai588]

@ooooo-create 可以先看看，能不能尝试把中文文档label的问题拆解成一个个任务

[ooooo-create]

@ooooo-create 可以先看看，能不能尝试把中文文档label的问题拆解成一个个任务

🙀🙀🙀🙀🙀
1.判断当前文件 lable 是否正确
(1)遍历docs.api.paddle 下面的每一个文件 rst 文件，对于文件记录下当前文件目录和文件名称(除去_cn.rst)，和文件第一行，.. cn():加上英文 label( 用路径和名称)(paddle.abs-＞api_paddle_add)，和那个对比（.. _cn_api_paddle_add:）。
不对的直接就替换？😂
（2）顺便把两个对应的 label 放入表格
（方便查找，可能 api 数量太多；用眼睛看也能修改成功吗？）
（3）顺便记录下有 ref 引用 的文件

2.把 包含 ref 文件，里面 ref 的 label 按照表格查找对应值进行修改
要是拆分任务的话大概就是就是拆分第二步？
或者第一步分目录吗，我想的是要是有 ref，选的话可能有些东西就被重复干了，(其实是我也没仔细看引用是不是大概在同一目录😓,感觉不太好吧

[SigureMo]

要是拆分任务的话大概就是就是拆分第二步？

感觉我们这个是不需要拆分任务的，应该直接一个 PR 修改就行

这里说的「拆解任务」就是你将整个任务拆成 1、2、3 几个步骤这样就行，已经做的很好了

此外，为了规范化，我们应当在中文 API 文档发生改动 / 添加时检查其 label 是否符合新规范

文档写作模板中针对 api_label 的规范增加相应描述

之后可以考虑上这几部分

[sunzhongkai588]

不对的直接就替换？

实操中可能还有考虑一些情况，比如某 api 下的 overview 文档的 label 该怎么定义（如 jit 的 overview 就是 .. _cn_overview_jit:，尽量考虑好各种情况和对应规范即可

要是拆分任务的话大概就是就是拆分第二步？

感觉我们这个是不需要拆分任务的，应该直接一个 PR 修改就行

任务要不要拆看 @ooooo-create 师傅叭。像第一步，如果你能直接写个批量替换rst文件第一行标签的脚本，那直接自己做了就OK。像第二步替换 ref ，如果你得手工改并且感觉工作量大的话，放任务也行。（嘿嘿不过还是建议尽量自己尝试一下）

此外，为了规范化，我们应当在中文 API 文档发生改动 / 添加时检查其 label 是否符合新规范

文档写作模板中针对 api_label 的规范增加相应描述

一师傅说的这两点我补充一下

• 制定一个新规范的话，需要能在 CI检查 中体现，以便于拦截不符合规范的PR。

• 我们的官网文档中有关于很多写作规范的描述文档，比如 API文档写作规范 。制定 api_label 新规范的话，需要也同步在对外公开文档上，有利于我们开发者了解最新信息。
  @ooooo-create

[ooooo-create]

实操中可能还有考虑一些情况，比如某 api 下的 overview 文档的 label 该怎么定义（如 jit 的 overview 就是 .. _cn_overview_jit:，尽量考虑好各种情况和对应规范即可

看了下有两种一个是overview，还有个少见的en，paddle.tensor里面的overview_en?

任务要不要拆看 @ooooo-create 师傅叭。像第一步，如果你能直接写个批量替换rst文件第一行标签的脚本，那直接自己做了就OK。像第二步替换 ref ，如果你得手工改并且感觉工作量大的话，放任务也行。（嘿嘿不过还是建议尽量自己尝试一下）

自己试试吧

此外，为了规范化，我们应当在中文 API 文档发生改动 / 添加时检查其 label 是否符合新规范

• 制定一个新规范的话，需要能在 CI检查 中体现，以便于拦截不符合规范的PR。
• 我们的官网文档中有关于很多写作规范的描述文档，比如 API文档写作规范 。制定 api_label 新规范的话，需要也同步在对外公开文档上，有利于我们开发者了解最新信息。
  @ooooo-create

1. 公开文档，或许也要在这添加？
   
   （对ci不了解）
2. 对文件本身，可以获取文件路径吗？然后en修改添加上.. _cn 和 :，特别对overview的情况判断。
3. 对于ref的label检查，就把label反向拆解成文件路径（同样考虑_cn_overview）的形式，通过文件是否存在，来判断，在ci上不知道能不能实现,
   （a 正确，引用b，结果没有）（a本身不正确，继续检测引用的）给出提示信息

[SigureMo]

对于ref的label检查，就把label反向拆解成文件路径（同样考虑_cn_overview）的形式，通过文件是否存在，来判断，在ci上不知道能不能实现,

可以的，这是一个检查项，即「引用正确性检查」，我们还可以增加一个「label 定义正确性检查」，即检查一个 API 文档第一行的 label 是不是符合规范的，这个检查流程和之前的从「文件路径」-> ... -> 「API label」的检查是一致的，只不过将它放到 CI 进行例行检查

[ooooo-create]

筛选了一下，发现Overview_cn.rst里面包含多个label，此外还有一个包含两个：label/docs/docs/api/paddle/profiler/Profiler_cn.rst

1. 感觉Overview_cn.rst本身的label也不是api,不需要修改?
2. 对应两个label的那个，我觉得还是得拆出来，好规范

[SigureMo]

感觉Overview_cn.rst本身的label也不是api,不需要修改?

嗯 Overview_cn.rst 的 label 本身不是 API，可以不用修改

对应两个label的那个，我觉得还是得拆出来，好规范

只有一个嘛？一个的话拆出来也是不太好发任务的 😂

[ooooo-create]

只有一个嘛？一个的话拆出来也是不太好发任务的 😂

说是我自己想把拆成两个文件，没有发任务🤩，应当是一个文件，一个label的吧。看了就那一个文件，我感觉就直接把第二个label删了就行，不用拆分文件了，这个label应当是多加的？

[SigureMo]

说是我自己想把拆成两个文件，没有发任务🤩，应当是一个文件，一个label的吧。看了就那一个文件，我感觉就直接把第二个label删了就行，不用拆分文件了，这个label应当是多加的？

不可以删的，一个文件两个 label 也是没问题的，因为后面的 label 指向了具体的子 API，可以搜一下，这个 label 是在别的地方有引用的

[ooooo-create]

不可以删的，一个文件两个 label 也是没问题的，因为后面的 label 指向了具体的子 API，可以搜一下，这个 label 是在别的地方有引用的

单个label的文件和其引用，我可能（还没有检验）转换好了，我感觉对于多个label的文件，就是判断每行以.. _cn开头，然后寻找接下来第一个copyfrom的那一行的api? 然后这个多label要是在ci中检查的话，只能对于.. _cn格式没错的进行检查，

[SigureMo]

我感觉对于多个label的文件，就是判断每行以.. _cn开头，然后寻找接下来第一个copyfrom的那一行的api?

我觉得只要检查第一个 label 即可，因为第一个 label 才是整个文件的 label，之后的都是子 API label

[ooooo-create]

许多文件中的ref: 里面涉及到 fluid的label？，这些需要对应的找api迁移文档，可以开展个任务？

[SigureMo]

许多文件中的ref: 里面涉及到 fluid的label？，这些需要对应的找api迁移文档，可以开展个任务？

嗯，我今天还和孙师傅说来着，如果发现有 fluid API 的 label，可以考虑统计下，发个任务，不过不是说带 fluid 的 label 都是 fluid API 的，有些是旧的 API 文档迁移出来但没有规范导致名字里带 fluid 的

对于 fluid API label，可以考虑

• 看看有没有相应的新 API 可以替代
• 如果没有就看看以合适的方式删除

当然这个工作量很大，需要拆分一下，可以按照 label 进行拆分

[sunzhongkai588]

• 看看有没有相应的新 API 可以替代
• 如果没有就看看以合适的方式删除

可以先初步参考 Paddle 1.8 与 Paddle 2.0 API 映射表，但也不全，得 case by case 的看。如果开发者无法确定的，可以收集起来然后我找建业问，已经和他打过招呼了

[ooooo-create]

我这里判断好像引用的只有三十几个，还有些是重复的，感觉我是不是漏掉了什么

[SigureMo]

o 师傅准备好就可以提个 tracking issue 来追踪这些任务了，可以在 tracking issue 里来写一下具体的任务拆分

[ooooo-create]

是先把fluid的改好，然后我统一转换其他的吗？还是我先转换，然后再处理fluid？

[SigureMo]

我觉得先把非 fluid 改好比较合适吧