docs
docs copied to clipboard
PaddlePaddle
【Docathon】补充Overview文档相关API描述
一、背景
飞桨官网的 API 文档，有中文和英文两个版本，都存储于 GitHub 中，并通过技术手段转为 HTML 文件后呈现在官网。
- 中文 API 文档存储于 docs 仓库下，具体路径为 PaddlePaddle/docs/docs/api/paddle。
- 英文 API 文档存储于 Paddle 仓库下的对应的 API 源码中，具体路径为 PaddlePaddle/Paddle/python/paddle。
原则上每一个中文 API 文档，都需要在对应目录下的 Overview 页面有描述，并且是一一对应的关系，但目前部分 Overview 文档中的 API 描述存在缺失。
[!NOTE] 以 paddle.amp.debugging.collect_operator_stats 为例，该 API 理应在 paddle.amp 文件夹下的 Overview 页面中的 Debug 相关辅助类有对应描述，但实际是缺失的。
因此，你需要在对应 amp 文件夹下的 Overview_cn.rst 文件中增加对应描述。
二、原因分析
中文文档中 Overview 是通过 :ref: 的格式进行映射的。一般会造成其描述缺失的就是其 Overview_cn.rst 缺乏相应的" :ref: 引用。
以 paddle.amp.debugging.DebugMod 为例，:ref: 引用写法如下：
https://github.com/PaddlePaddle/docs/blob/962078482ad8c2bc9dfa2f5b9e2787bcec1851a3/docs/api/paddle/amp/Overview_cn.rst?plain=1#L75
三、解决方法
通过在相应位置添加 " :ref:`API<相关 API 路径>` " 补充 Overview 文档中缺失的 API 描述、以 paddle.add 为例：
- 首先通过路径找到相应的 Overview 文档的 rst 文件，如下图
- 其次相关文档补齐，paddle.add 的功能是与 tensor 数学操作有关，则找到相应的位置如下
按照
" :ref:`API<相关 API 路径>` "，"API 功能"添加描述
四、任务描述
任务认领
[!IMPORTANT] 请务必严格按照格式填写，否则无法快乐开源小助手无法自动更新信息
1. Issue 回复格式：
为了自动填写报名信息，需要在 issue 下回复报名信息，如果报名格式不正确，则会在 comment 区提示报名不正确，格式如下：
【报名】: 2、3、6-10
其中【报名】: 后直接是报名的赛题序号，多个赛题之间需要用中文顿号
、分隔，多个连续赛题可以用横线表示
2. PR 标题格式：
[Docathon][Add Overview Doc No.2、3、6-10]+相关描述
PR 的标题中以 [Docathon][Add Overview Doc No.xxxx] 开头即可，程序会自动提取赛题编号并更新榜单。
一个 PR 也可以提交多个赛题，多个赛题间以顿号或横线分隔，比如 No.24、26-28、30 赛题。
3. PR 内容：
描述新增了哪些 Overview 的 API 描述、附上中文文档链接、并 @Turingg 和 @sunzhongkai588
看板信息
| 任务方向 | 任务数量 | 提交作品 / 任务认领 | 提交率 | 完成 | 完成率 |
|---|---|---|---|---|---|
| Docathon | 36 | 36 / 36 | 100.0% | 28 | 77.78% |
统计信息
排名不分先后 @Turingg (2) @hu-qi (15) @Wang-ZengWei (1) @StellaZYing (3) @gsq7474741 (1) @Harryoung (6)
