【Docathon】为 Tensor API 文档增加图例

[sunzhongkai588]

1. Motivation

之前在发起文档评测任务的过程中，有开发者反馈希望能够为 API 文档增加图例以直观展示 Tensor 操作变化。基于此，为了提高 Paddle 框架的用户友好性和可理解性，我们尝试号召社区为涉及 Tensor 元素操作的 API 文档增加图例说明。这包括但不限于转置（transpose）、重塑（reshape）、切片（slice）等操作，需要增加图例的具体 API 请见下文。

图例应该清晰地展示 Tensor 在操作前后的形状变化，以及元素位置的变动，从而帮助用户直观理解这些操作的效果，提升文档的易读性。

2. 能获得什么收益

• 提高可理解性：通过图例，使用户能够直观地理解 Tensor 操作的具体效果，尤其是形状和维度变化。
• 增强文档质量：丰富的视觉元素可以提升文档的整体质量和用户满意度。
• 促进学习效率：帮助新用户快速掌握特定 Tensor 操作的概念，加快上手过程。

3. 图例要求

图例内容要求

• 明确标示操作前后 Tensor 的维度和形状，例如，从一个 2x3 的 Tensor reshape 到一个 3x2 的 Tensor。
• 需要标注 Tensor 的每个维度，尤其是在形状发生变化操作时需要标明维度（axis = 0 axis = 1 等）可参考下方的示例 PR 标注维度。
• 用序号或箭头展示操作前后的变化。
• 特别是在进行如 transpose、slice 等操作时，清晰地指出哪些元素被移动或修改。（最直观的方式就是展示变化前后的 Tensor 值）
• 对于涉及到复杂操作的 Tensor API，需提供分步骤的图例（如先 reshape 后 transpose），展示每一步骤操作后的 Tensor 状态。

图例风格和格式

• 简洁明了：图例应避免不必要的复杂性，确保即便是初学者也能一目了然地理解 Tensor 操作的效果。
• 标注清晰：图例中包含的文字描述应简洁并易于理解。考虑到文档的国际化和本地化需求，如需包含文字，请使用英文。
• 格式统一：推荐使用 PNG 格式，以保持图像质量并确保兼容性。图例大小应适中，优化 Web 和移动设备的显示效果。

注意事项

Important

1. 图片文件统一存放在 docs 仓库下的 images/api_legend 目录下，以 API 名称命名，如 reshape.png；
2. 单张图片大小不超过 200 kb；
3. API 中、英文文档均需要添加对图例的引用和简短的描述，建议先从中文 docs 仓库提 PR；
4. 英文文档（Paddle 仓库）里引用的也是 docs 仓库目录下的图片，但需要注意按照如下路径： https://githubraw.cdn.bcebos.com/PaddlePaddle/docs/develop/docs/images/api_legend/...
5. 绘图工具不限，最方便的方式就是直接用 PPT 做（狗头），推荐用 https://app.diagrams.net 工具做

参考 PR

• 为 crop 中文文档增加图例：[Docathon][Add API Legend No.6]add the picture of crop #6786
• 为 crop 英文文档增加图例：[Docathon][Add API Legend No.6] Add legend for crop API Paddle#68462

4. 任务列表

为以下的 API 中、英文文档增加图例，具体链接见 Tensor 元素操作的 API 文档：

序号	需要增加图例的 API 文档	API 研发负责人	认领人/状态/PR
1	paddle.broadcast_to	@DefTruth	@hu-qi #6633 @hanyang2508 #6950 #69729 @yangrongxinuser #6977
2	paddle.broadcast_tensors	@JiabinYang	@Liyulingyue #6941 #69266 @wangjipeng1217 #6987
3	paddle.cast	@Vvsmile	@GoldenStain #6827 #67287 @lichen580
4	paddle.chunk	@Vvsmile	@successfulbarrier #6765
5	paddle.concat	@wuhuachaocoding	@Guanhuachen2003 #6789 #67100
6	paddle.crop	@DefTruth	@Aoraki-Dream #6786 #68462
7	paddle.expand	@DefTruth	@Caogration #6764 @ZHOU05030 @rich04lin #6975 @yangrongxinuser #6978 #70143 @Wzj02200059 #7018 #7019
8	paddle.expand_as	@DefTruth	@Sekiro-x #6771
9	paddle.flatten	@BiynXu	@Lans1ot #6770 #6857 #6896 @yuelengqianshan4
10	paddle.flip	@Caozhou1995	@yeteye #6777 #6816
11	paddle.rot90	@danleifeng	@Luohongzhige #6787
12	paddle.gather	@sneaxiy	@lwkhahaha #6793
13	paddle.gather_nd	@sneaxiy	@ppo11111 @MrYo666 #6943
14	paddle.reshape ✅	@heavyrain-lzy
15	paddle.atleast_1d	@luotao1	@UfanLee #6990 @lichen580
16	paddle.atleast_2d	@luotao1	@Albresky #6991 #70242 @Victor-Bayim
17	paddle.atleast_3d	@luotao1	@mercutiojohn @Y5ive9ine
18	paddle.roll	@FeixLiu	@haoyu2022 #6810 #67061
19	paddle.scatter	@FeixLiu	@xz-alex @jiachengdai #6973 #69749
20	paddle.scatter_nd	@FeixLiu	@Chris-godz #6931
21	paddle.scatter_nd_add	@FeixLiu	@ndyysheep #6964
22	paddle.shard_index	@tianhaodongbd	@xu8117 #6939 #70215
23	paddle.slice	@zyfncg	@EgoistSA #6812 #67897
24	paddle.slice_scatter	@zoooo0820	@EgoistSA #6834 #6837 @ZHOU05030 #6974 @PolaKuma #69498
25	paddle.split	@tianhaodongbd	@yeteye #6815
26	paddle.tensor_split	@zoooo0820	@fufu0615 #6809 #66991
27	paddle.hsplit	@zoooo0820	@fufu0615 #6809
28	paddle.vsplit	@zoooo0820	@fufu0615 #6809
29	paddle.dsplit	@zoooo0820	@fufu0615 #6809
30	paddle.squeeze	@heliqi	@Whsjrczr #6802 @fufu0615 #6809
31	paddle.stack	@YanhuiDua	@mori0umi #6933 #69404
32	paddle.strided_slice	@heliqi	@jincheng23 @kanze1
33	paddle.tile	@wz1qqx	@Hui-code06 #6923
34	paddle.transpose	@heliqi	@SCUcookie #6929 #69413
35	paddle.moveaxis	@zhwesky2010	@KDZZZZZZ #6902
36	paddle.tensordot	@From00	@yangrongxinuser #6971
37	paddle.unbind	@zhiqiu	@struim #6773 #6780 @WFLiu0327 #6963
38	paddle.unique	@Shicheng	@fxy1699 #6940 #6945 @knoka812
39	paddle.unique_consecutive	@GuoxiaWang	@PolaKuma @kineast #6967 #70136 #70163
40	paddle.unsqueeze	@heliqi	@zeroader #6944 #6951 #70048
41	paddle.unstack	@shentanyue	@yeteye #6840
42	paddle.as_complex	@GGBond8488	@Leoforever123 #6913 #68768
43	paddle.as_real	@GGBond8488	@Leoforever123 #6914
44	paddle.repeat_interleave	@tianhaodongbd	@fxy1699 @yangrongxinuser #6988 #70128
45	paddle.index_add	@Vvsmile	@KeithMaxwell #6938 @kineast
46	paddle.index_put	@zyfncg	@fxy1699 #6952
47	paddle.unflatten	@zoooo0820	@WFLiu0327 #6960 @LittleHeroZZZX #6954 #69396
48	paddle.as_strided	@wanghuancoder	@Sylence8 #6968 #69874
49	paddle.view	@wanghuancoder	@Wang-ZengWei #6826 @WSBG #6998
50	paddle.view_as	@wanghuancoder	@Marcusryz #6774
51	paddle.unfold	@wanghuancoder	@zeroader #6951 #70048
52	paddle.masked_fill	@zoooo0820	@PolaKuma #6927 #69215
53	paddle.masked_scatter		@fxy1699 #6953 @yangrongxinuser #6979 #70145 @Neo-WY
54	paddle.diagonal_scatter	@zxcd	@wwwuyan #6966 #6994 #69895
55	paddle.index_fill	@zoooo0820	@xu8117 #6939 #70215
56	paddle.column_stack	@zoooo0820	@ChengNanFlower #6903 #6905 #6912
57	paddle.row_stack	@zoooo0820	@ChengNanFlower #6912
58	paddle.hstack	@zoooo0820	@MufanColin #6768 #66856
59	paddle.vstack	@zoooo0820	@yeteye #6817
60	paddle.dstack	@zoooo0820	@yeteye #6842 @Eimy-san

任务认领

Important

请务必严格按照格式填写，否则无法快乐开源小助手无法自动更新信息

1. Issue 回复格式：

为了自动填写报名信息，需要在 issue 下回复报名信息，如果报名格式不正确，则会在 comment 区提示报名不正确，格式如下：

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

其中【报名】: 后直接是报名的赛题序号，多个赛题之间需要用中文顿号、分隔，多个连续赛题可以用横线表示

2. PR 标题格式：

[Docathon][Add API Legend No.2、3、6-10]+相关描述

PR 的标题中以 [Docathon][Add API Legend No.xxxx] 开头即可，程序会自动提取赛题编号并更新榜单。
一个 PR 也可以提交多个赛题，多个赛题间以顿号或横线分隔，比如 No.24、26-28、30 赛题。

3. PR 内容：

描述新增了哪些 API 文档的图例、附上中文文档链接、并 @对应研发负责人 和 @sunzhongkai588

看板信息

任务方向	任务数量	提交作品 / 任务认领	提交率	完成	完成率
Docathon	60	57 / 59	95.0%	39	65.0%

统计信息

排名不分先后 @hanyang2508 (1) @Liyulingyue (1) @GoldenStain (1) @successfulbarrier (1) @Guanhuachen2003 (1) @Aoraki-Dream (1) @yangrongxinuser (2) @Sekiro-x (1) @Lans1ot (1) @yeteye (5) @Luohongzhige (1) @lwkhahaha (1) @haoyu2022 (1) @jiachengdai (1) @ndyysheep (1) @EgoistSA (1) @PolaKuma (2) @fufu0615 (4) @Whsjrczr (1) @mori0umi (1) @SCUcookie (1) @Leoforever123 (2) @KeithMaxwell (1) @LittleHeroZZZX (1) @Marcusryz (1) @wwwuyan (1) @ChengNanFlower (2) @MufanColin (1)

[hu-qi]

【报名】: 1

[successfulbarrier]

【报名】：4

[Marcusryz]

【报名】: 50

[Caogration]

【报名】: 7

[Sekiro-x]

【报名】: 8

[Guanhuachen2003]

【报名】: 5

[MufanColin]

【报名】：58

[struim]

【报名】：37

[yeteye]

【报名】：10

[Aoraki-Dream]

【报名】: 6

[Luohongzhige]

【报名】: 11

[lwkhahaha]

【报名】: 12

[yeteye]

【报名】: 25

[GoldenStain]

【报名】: 3

[fufu0615]

【报名】: 26、27、28、29

[Whsjrczr]

【报名】：30

[haoyu2022]

【报名】: 18

[yeteye]

【报名】: 41、59、60

[EgoistSA]

【报名】: 23

[Wang-ZengWei]

【报名】: 49

[EgoistSA]

【报名】: 24

[KDZZZZZZ]

【报名】: 35

[fxy1699]

【报名】: 44

[yangrongxinuser]

【报名】: 36

[jincheng23]

【报名】: 32

[ndyysheep]

【报名】: 21

[wwwuyan]

【报名】：54

[Sylence8]

【报名】: 48

[kineast]

【报名】：39

[mercutiojohn]

【报名】: 17

[ZHOU05030]

【报名】: 7

[WFLiu0327]

【报名】: 37

[rich04lin]

【报名】: 7

[jiachengdai]

【报名】: 19

[kanze1]

【报名】: 32

[kineast]

【报名】：45

[ZHOU05030]

【报名】：24

[Y5ive9ine]

【报名】：17

[WSBG]

【报名】: 49

[lichen580]

【报名】：3

[Victor-Bayim]

【报名】: 16

[lichen580]

【报名】: 15

[yangrongxinuser]

【报名】: 1

[yangrongxinuser]

【报名】: 7

[wangjipeng1217]

【报名】: 2

[yangrongxinuser]

【报名】: 53

[Neo-WY]

【报名】: 53

[Eimy-san]

【报名】: 60

[yangrongxinuser]

【报名】：44

[Wzj02200059]

【报名】: 7