本文最后更新于 2024-11-09，文章内容可能已经过时。

修改飞桨文档，往往是许多飞桨社区开发者们参与飞桨开源活动的起点。通过给飞桨 API 文档增加图例并提交 PR，你将熟悉 Tensor 的基础操作和为 Paddle 社区贡献代码的流程规范。 你可以直接在 Issue 处进行进行认领并提交 PR 。

Motivation

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

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

收益

  • 提高可理解性：通过图例，使用户能够直观地理解 Tensor 操作的具体效果，尤其是形状和维度变化。

  • 增强文档质量：丰富的视觉元素可以提升文档的整体质量和用户满意度。

  • 促进学习效率：帮助新用户快速掌握特定 Tensor 操作的概念，加快上手过程。

图例要求

图例内容要求

  • 明确标示操作前后 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