【Docathon】修复文档注解

[sunzhongkai588]

Note

Motivation： #7125 by @ooooo-create （o 师傅）

背景

飞桨官网的 API 文档采用 ReStructuredText (.rst) 格式编写，经渲染后以 HTML 格式呈现。.rst 文件对缩进、空行等格式非常敏感，稍有不当便可能导致渲染异常。

目前，飞桨 API 文档中广泛使用 .. note:: 的注解语法，目的是提醒开发者使用 API 时需额外注意的事项。

以 amax 为例，官网显示的注解效果如下图红框所示

对应 .rst 源码为：

docs/docs/api/paddle/amax_cn.rst

Lines 11 to 13 in 50e8abc

	.. note::
	对输入有多个最大值的情况下，max 将梯度完整传回到最大值对应的位置，amax 会将梯度平均传回到最大值对应的位置

Important

详情参考 API 文档书写规范-注解

问题

目前，有部分 API 文档的注解内容未严格遵守缩进要求，导致渲染异常。例如：

docs/docs/api/paddle/greater_equal_cn.rst

Lines 10 to 11 in 50e8abc

	.. note::
	输出的结果不返回梯度。

正确示例如下（需缩进）：

 .. note:: 
     输出的结果不返回梯度。

经排查发现以下文件均存在类似问题，需要统一修正。

任务描述

Important

可参考 @Echo-Nie 提交的 PR #7132 进行修复

请修复以下文件的 .. note:: 注解缩进问题，确保注解内容缩进正确，官网渲染正常。

待修复文档清单：

序号	文件路径	认领人/状态/PR
1	docs/api/paddle/add_cn.rst	@Echo-Nie #7132
2	docs/api/paddle/greater_equal_cn.rst	@Echo-Nie #7132
3	docs/api/paddle/tensordot_cn.rst	@Echo-Nie #7132
4	docs/api/paddle/linalg/eigvals_cn.rst	@Echo-Nie #7132
5	docs/api/paddle/metric/Auc_cn.rst	@hanlintang #7138 @Echo-Nie #7164
6	docs/api/paddle/metric/Precision_cn.rst	@hanlintang #7138 @Echo-Nie #7164
7	docs/api/paddle/metric/Recall_cn.rst	@hanlintang #7138 @Echo-Nie #7164
8	docs/api/paddle/nn/BatchNorm1D_cn.rst	@KANGslay #7141 @cuiyu-ai #7214
9	docs/api/paddle/nn/BatchNorm2D_cn.rst	@KANGslay #7141 @hanlintang #7222
10	docs/api/paddle/nn/BatchNorm3D_cn.rst	@KANGslay #7141 @hanlintang #7222
11	docs/api/paddle/nn/InstanceNorm1D_cn.rst	@Keywennn #7140 @Echo-Nie #7213
12	docs/api/paddle/nn/InstanceNorm2D_cn.rst	@Keywennn #7140 @Echo-Nie #7213
13	docs/api/paddle/nn/InstanceNorm3D_cn.rst	@Keywennn #7140 @Echo-Nie #7213
14	docs/api/paddle/optimizer/Adadelta_cn.rst	@Ismoothly @xxm2892 #7185 #7184 @HangFu7 #7169
15	docs/api/paddle/optimizer/Adamax_cn.rst	@Haroldlhl #7162 @xxm2892 #7185 #7184
16	docs/api/paddle/optimizer/Adam_cn.rst	@Haroldlhl #7162 @xxm2892 #7185 #7184 @cuiyu-ai #7186
17	docs/api/paddle/optimizer/Lamb_cn.rst	@Djraemon #7172 @xxm2892 #7185 #7184 @yueshehanjiang #7161
18	docs/api/paddle/optimizer/LBFGS_cn.rst	@Djraemon #7172 @xxm2892 #7185 #7184 @yueshehanjiang #7161
19	docs/api/paddle/optimizer/Momentum_cn.rst	@Kang-8846 #7145
20	docs/api/paddle/optimizer/NAdam_cn.rst	@ZMS-PNG @594233 #7148 @rich04lin #7150
21	docs/api/paddle/optimizer/Optimizer_cn.rst	@594233 #7148 @rich04lin #7150
22	docs/api/paddle/optimizer/RAdam_cn.rst	@594233 #7148 @rich04lin #7150 @Jacoblincc
23	docs/api/paddle/optimizer/RMSProp_cn.rst	@rich04lin #7150 @Jacoblincc
24	docs/api/paddle/optimizer/SGD_cn.rst	@rich04lin #7150 @Jacoblincc
25	docs/api/paddle/static/Executor_cn.rst	@zengpufan #7157 #7174 @turbozhuo #7171
26	docs/api/paddle/static/Program_cn.rst	@zengpufan #7157 @turbozhuo #7171 @cuiyu-ai #7215
27	docs/api/paddle/static/set_program_state_cn.rst	@594233 #7155
28	docs/api/paddle/static/Variable_cn.rst	@594233 #7155
29	docs/api/paddle/static/nn/conv2d_transpose_cn.rst	@rich04lin #7154 @Ericsciencer
30	docs/api/paddle/static/nn/conv3d_transpose_cn.rst	@rich04lin #7154 @Ericsciencer
31	docs/api/paddle/static/nn/embedding_cn.rst	@rich04lin #7154
32	docs/api/paddle/static/nn/sequence_concat_cn.rst	@rich04lin #7154
33	docs/api/paddle/static/nn/sequence_conv_cn.rst	@rich04lin #7154
34	docs/api/paddle/static/nn/sequence_enumerate_cn.rst	@rich04lin #7154
35	docs/api/paddle/static/nn/sequence_expand_as_cn.rst	@rich04lin #7154 @XiaoLai0-0 #7165
36	docs/api/paddle/static/nn/sequence_expand_cn.rst	@rich04lin #7154 @XiaoLai0-0 #7173
37	docs/api/paddle/static/nn/sequence_first_step_cn.rst	@rich04lin #7154 @quite125
38	docs/api/paddle/static/nn/sequence_last_step_cn.rst	@rich04lin #7154
39	docs/api/paddle/static/nn/sequence_pad_cn.rst	@Echo-Nie #7153
40	docs/api/paddle/static/nn/sequence_pool_cn.rst	@Echo-Nie #7153 #7178
41	docs/api/paddle/static/nn/sequence_reshape_cn.rst	@Echo-Nie #7153
42	docs/api/paddle/static/nn/sequence_reverse_cn.rst	@Echo-Nie #7153
43	docs/api/paddle/static/nn/sequence_slice_cn.rst	@Echo-Nie #7153
44	docs/api/paddle/static/nn/sparse_embedding_cn.rst	@Echo-Nie #7153 #7177

修复完成后，文档将在官网正确渲染。参与修复的开发者将获得官网贡献者展示机会🎉。

任务认领

Note

1. Issue 回复格式：
在 issue 下回复报名信息，格式如下：

【报名】: 2、3、6-10

多个序号之间用中文顿号、隔开，连续序号用横线连接。

Note

2. PR 标题格式：

[Docathon][Fix note No.2、3、6-10]

Note

3. PR 内容：
描述本次修改内容，附上该 issue 链接，并 @Echo-Nie @sunzhongkai588 review。

参考资料

• 文档贡献指南
• API 文档书写规范
• Python 文档示例代码书写规范

---

🎯 欢迎大家积极参与，提升文档质量，共建飞桨社区！

看板信息

任务方向	任务数量	提交作品 / 任务认领	提交率	完成	完成率
修复文档注解	44	44 / 44	100.0%	44	100.0%

统计信息

排名不分先后 @Echo-Nie (13) @hanlintang (5) @cuiyu-ai (2) @HangFu7 (1) @Haroldlhl (2) @yueshehanjiang (2) @Kang-8846 (1) @rich04lin (15) @zengpufan (1) @594233 (2)

[Echo-Nie]

【报名】：1-4

[hanlintang]

【报名】：5-7

[KANGslay]

【报名】：8-10

[Keywennn]

【报名】：11-13

[Ismoothly]

【报名】：14

[Haroldlhl]

【报名】：15-16

[Djraemon]

【报名】：17-18

[Kang-8846]

【报名】：19

[ZMS-PNG]

【报名】: 20

[594233]

【报名】: 20-22

[rich04lin]

【报名】: 20-24

[zengpufan]

【报名】: 25-26

[Echo-Nie]

【报名】：39-44

[rich04lin]

【报名】：29-38

[594233]

【报名】: 27-28

[Ericsciencer]

【报名】: 29-30

[xxm2892]

【报名】: 14-18

[yueshehanjiang]

【报名】: 17-18

[XiaoLai0-0]

【报名】: 35-36

[quite125]

【报名】: 37

[HangFu7]

【报名】：14

[cuiyu-ai]

【报名】：16

[Echo-Nie]

【报名】：11-13

[cuiyu-ai]

【报名】：8, 26

[Jacoblincc]

【报名】: 22-24

[hanlintang]

【报名】: 9、10

[luotao1]

【Docathon】修复文档注解 已全部完成，感谢参与的小伙伴们！

排名不分先后 @Echo-Nie (13) @hanlintang (5) @cuiyu-ai (2) @HangFu7 (1) @Haroldlhl (2) @yueshehanjiang (2) @Kang-8846 (1) @rich04lin (15) @zengpufan (1) @594233 (2)

欢迎继续参与 快乐开源的其他任务 ！