PaddlePaddle
【Docathon】为 Tensor API 文档增加图例
1. Motivation
之前在发起文档评测任务的过程中，有开发者反馈希望能够为 API 文档增加图例以直观展示 Tensor 操作变化。基于此，为了提高 Paddle 框架的用户友好性和可理解性，我们尝试号召社区为涉及 Tensor 元素操作的 API 文档增加图例说明。这包括但不限于转置（transpose）、重塑（reshape）、切片（slice）等操作，需要增加图例的具体 API 请见下文。
图例应该清晰地展示 Tensor 在操作前后的形状变化，以及元素位置的变动，从而帮助用户直观理解这些操作的效果，提升文档的易读性。
2. 能获得什么收益
- 提高可理解性：通过图例，使用户能够直观地理解 Tensor 操作的具体效果，尤其是形状和维度变化。
- 增强文档质量：丰富的视觉元素可以提升文档的整体质量和用户满意度。
- 促进学习效率：帮助新用户快速掌握特定 Tensor 操作的概念，加快上手过程。
3. 图例要求
图例内容要求
- 明确标示操作前后 Tensor 的维度和形状，例如，从一个 2x3 的 Tensor reshape 到一个 3x2 的 Tensor。
- 需要标注 Tensor 的每个维度，尤其是在形状发生变化操作时需要标明维度（
axis = 0axis = 1等）可参考下方的示例 PR 标注维度。 - 用序号或箭头展示操作前后的变化。
- 特别是在进行如 transpose、slice 等操作时，清晰地指出哪些元素被移动或修改。（最直观的方式就是展示变化前后的 Tensor 值）
- 对于涉及到复杂操作的 Tensor API，需提供分步骤的图例（如先 reshape 后 transpose），展示每一步骤操作后的 Tensor 状态。
图例风格和格式
- 简洁明了：图例应避免不必要的复杂性，确保即便是初学者也能一目了然地理解 Tensor 操作的效果。
- 标注清晰：图例中包含的文字描述应简洁并易于理解。考虑到文档的国际化和本地化需求，如需包含文字，请使用英文。
- 格式统一：推荐使用 PNG 格式，以保持图像质量并确保兼容性。图例大小应适中，优化 Web 和移动设备的显示效果。
注意事项
[!IMPORTANT]
- 图片文件统一存放在 docs 仓库下的 images/api_legend 目录下，以 API 名称命名，如
reshape.png；- 单张图片大小不超过 200 kb；
- API 中、英文文档均需要添加对图例的引用和简短的描述，建议先从中文 docs 仓库提 PR；
- 英文文档（Paddle 仓库）里引用的也是 docs 仓库目录下的图片，但需要注意按照如下路径：
https://githubraw.cdn.bcebos.com/PaddlePaddle/docs/develop/docs/images/api_legend/...- 绘图工具不限，最方便的方式就是直接用 PPT 做（狗头），推荐用 https://app.diagrams.net 工具做
参考 PR
- 为 reshape 中文文档增加图例：https://github.com/PaddlePaddle/docs/pull/6786
- 为 reshape 英文文档增加图例：https://github.com/PaddlePaddle/Paddle/pull/68462
4. 任务列表
为以下的 API 中、英文文档增加图例，具体链接见 Tensor 元素操作的 API 文档：
| 序号 | 需要增加图例的 API 文档 | API 研发负责人 | 认领人/状态/PR |
|---|---|---|---|
| 1 | paddle.broadcast_to | @DefTruth | @hu-qi  #6633 |
| 2 | paddle.broadcast_tensors | @JiabinYang | @hu-qi  |
| 3 | paddle.cast | @Vvsmile | @GoldenStain  #6827 |
| 4 | paddle.chunk | @Vvsmile | @successfulbarrier #6765 |
| 5 | paddle.concat | @wuhuachaocoding | @Guanhuachen2003 #6789 |
| 6 | paddle.crop | @DefTruth | @Aoraki-Dream #6786 |
| 7 | paddle.expand | @DefTruth | @Caogration #6764 |
| 8 | paddle.expand_as | @DefTruth | @Sekiro-x #6771 |
| 9 | paddle.flatten | @BiynXu | @Lans1ot #6770 #6857 #6896 |
| 10 | paddle.flip | @Caozhou1995 | @yeteye #6777 #6816 |
| 11 | paddle.rot90 | @danleifeng | @Luohongzhige #6787 |
| 12 | paddle.gather | @sneaxiy | @lwkhahaha #6793 |
| 13 | paddle.gather_nd | @sneaxiy | |
| 14 | ~paddle.reshape~ ✅ | @heavyrain-lzy | |
| 15 | paddle.atleast_1d | @luotao1 | @haoyu2022 |
| 16 | paddle.atleast_2d | @luotao1 | @haoyu2022 |
| 17 | paddle.atleast_3d | @luotao1 | @haoyu2022 |
| 18 | paddle.roll | @FeixLiu | @haoyu2022 #6810 |
| 19 | paddle.scatter | @FeixLiu | |
| 20 | paddle.scatter_nd | @FeixLiu | |
| 21 | paddle.scatter_nd_add | @FeixLiu | |
| 22 | paddle.shard_index | @tianhaodongbd | |
| 23 | paddle.slice | @zyfncg | @EgoistSA #6812 |
| 24 | paddle.slice_scatter | @zoooo0820 | @EgoistSA #6834 #6837 |
| 25 | paddle.split | @tianhaodongbd | @yeteye #6815 |
| 26 | paddle.tensor_split | @zoooo0820 | @fufu0615 #6809 |
| 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 | @yeteye |
| 32 | paddle.strided_slice | @heliqi | |
| 33 | paddle.tile | @wz1qqx | @Hui-code06 |
| 34 | paddle.transpose | @heliqi | |
| 35 | paddle.moveaxis | @zhwesky2010 | @KDZZZZZZ #6902 |
| 36 | paddle.tensordot | @From00 | |
| 37 | paddle.unbind | @zhiqiu | @struim #6773 #6780 |
| 38 | paddle.unique | @Shicheng | |
| 39 | paddle.unique_consecutive | @GuoxiaWang | |
| 40 | paddle.unsqueeze | @heliqi | |
| 41 | paddle.unstack | @shentanyue | @yeteye #6840 |
| 42 | paddle.as_complex | @GGBond8488 | @Leoforever123 #6913 |
| 43 | paddle.as_real | @GGBond8488 | @Leoforever123 #6914 |
| 44 | paddle.repeat_interleave | @tianhaodongbd | |
| 45 | paddle.index_add | @Vvsmile | |
| 46 | paddle.index_put | @zyfncg | |
| 47 | paddle.unflatten | @zoooo0820 | |
| 48 | paddle.as_strided | @wanghuancoder | |
| 49 | paddle.view | @wanghuancoder | @Wang-ZengWei #6826 |
| 50 | paddle.view_as | @wanghuancoder | @Marcusryz #6774 |
| 51 | paddle.unfold | @wanghuancoder | |
| 52 | paddle.masked_fill | @zoooo0820 | |
| 53 | paddle.masked_scatter | ||
| 54 | paddle.diagonal_scatter | @zxcd | |
| 55 | paddle.index_fill | @zoooo0820 | |
| 56 | paddle.column_stack | @zoooo0820 | @ChengNanFlower #6903 #6905 #6912 |
| 57 | paddle.row_stack | @zoooo0820 | @ChengNanFlower #6912 |
| 58 | paddle.hstack | @zoooo0820 | @MufanColin #6768 |
| 59 | paddle.vstack | @zoooo0820 | @yeteye #6817 |
| 60 | paddle.dstack | @zoooo0820 | @yeteye #6842 |
任务认领
[!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 | 32 / 38 | 53.33% | 25 | 41.67% |
统计信息
排名不分先后 @GoldenStain (1) @successfulbarrier (1) @Guanhuachen2003 (1) @Aoraki-Dream (1) @Sekiro-x (1) @Lans1ot (1) @yeteye (5) @Luohongzhige (1) @lwkhahaha (1) @haoyu2022 (1) @EgoistSA (1) @fufu0615 (4) @Whsjrczr (1) @Leoforever123 (1) @Marcusryz (1) @ChengNanFlower (2) @MufanColin (1)
