[Docs]飞桨 API 文档体验提升计划 #48047
Description
用于跟踪 Call-for-Contributions: API文档体验优化 各个任务的计划和进度
路线一：API文档问题修复
| 任务名称 | 任务说明 | 认领人 | PR情况 |
|---|---|---|---|
| 示例代码中移除第三方库numpy | 由于历史原因，paddle1.x中的tensor生成与打印需要依赖第三方库numpy来实现，因此在API文档中大量引入了第三方库numpy。当前paddle已经可以很好的支持独立的生成与打印，易用性有了比较大的提升，这一点需要在示例代码中做体现，因此在非必要的情况下，示例代码中应该移除第三方库numpy | @kevinng77 | #46765, #47042 (merged) #47483 (merged, 统一移除多余的 Numpy 依赖导入) #47555 (merged, 统一移除 Numpy + paddle.to_tensor 构建的输入) #47916 (merged, 补偿 #47555 中遗留问题) #48678 |
| DenseTensor 概念统一 | LoD 信息主要是为了处理的语言类模型而引入的机制设计，由于适配复杂，特殊情况多，相比传统的 Padding 机制维护成本高，Paddle 已经废弃了对该机制的维护。需要在文档中移除所有LoDTensor 概念的使用，统一飞桨基础框架的 DenseTensor 概念，使代码更容易理解与维护。 |
@Liyulingyue @Lemon-er | #48416 (merged) #48417 (merged) #48418 (merged) #48419 (merged) #48682 (merged) PaddlePaddle/docs#5486 |
| 对inplace api增加介绍信息 | inplace（原位操作），具体可参考tensor介绍，目前的API文档中对这部分介绍比较少，对新手不够友好（如 paddle.tanh_），需要在文档中增加说明或超链接，另外修复部分超链接失效的问题。详见issue：PaddlePaddle/docs#4766 | @ZhangYuef | PaddlePaddle/docs#5469 |
| 修复broadcasting说明的超链接失效问题 | 例如 paddle.add，修复方法可参考 paddle.broadcast_tensors，对提到支持broadcast的api，全量查找并统一替换为标准格式。可参考：#46347 | @enkilee | PaddlePaddle/docs#5441 #48434 |
| 对超链接没有生成的情况，进行全量检索与修复 | 参考飞桨文档相互引用，可以发现由于rst的特殊引用格式，导致很多习惯书写md文档的同学会使用错误的引用方式，导致超链接没有生成的情况，需要在html中全量查找并修复 | @whisky-12 @tianxingxia-cn | PaddlePaddle/docs#5521 |
| 处理API文档中的死链问题 | API文档死链扫描 ，由于文档中英文一致，需要确认一下中英文文档的超链接是否一致，如果遗漏，需要增加 | @jjyaoao | #48969 PaddlePaddle/docs#5500 |
| 英文API文档中的异常报错 | 飞桨的英文API文档是通过docstring编译生成的html页面，由于sphinx编译导致的报错有一部分会直接显示在文档中，严重影响用户体验，详见issue：PaddlePaddle/docs#5177 | @ustiniankw | #47448 （merged） #47986 （merged） 除fluid api外其他部分已完成全部修复，通过QA验收 |
| 在中文API文档中统一 Tensor 的描述 | 中文文档中存在少量将 Tensor 翻译为张量的情况，虽然没有什么问题，但是会造成理解上的困难，建议统一为 Tensor | @Liyulingyue @Atlantisming @sanbuphy | PaddlePaddle/docs#5477 PaddlePaddle/docs#5480 PaddlePaddle/docs#5523 |
| 在英文API文档中统一静态图模式与动态图模式的英文翻译 | dynamic graph mode 和 static graph mode，英文文档中出现了诸如 static mode、imperative mode、dygraph mode 等不规范的翻译，建议统一 | @lizechng @sanbuphy @Atlantisming | PaddlePaddle/docs#5467 PaddlePaddle/docs#5525 #49170 #49243 PaddlePaddle/docs#5535 |
路线二：飞桨API文档写作规范手册制定
可以参考 飞桨 API 文档的不规范之处及其规范化方案汇总、【当前版本】官网-API 文档书写规范
| 章节名称 | 内容规划（可调整） | 撰写认领人 | PR情况 |
|---|---|---|---|
| API命名方法与API介绍 | 飞桨API目录结构介绍，可直接参考 官网文档-API 设计和命名规范 API命名方法，含参数，区分class与function API介绍方法，如何用最简短的话讲清一个API是什么，怎么用 |
||
| 数字及数学公式的写法 | 数字、数值的写法 数学公式的写法 |
@DrRyanHuang | |
| 字母及标点符号的写法 | 中文标点 英文字母及标点 |
||
| 外部链接和超链接的写法 | 引用规范：包含引用API、站内文献、站外文献、论文等 超链接的使用，可以参考：飞桨文档相互引用 |
||
| 其他规范 | 空格、段落的规范使用 字体、色块的写法（加粗、斜体、灰色底块等） 图、表的使用（图题、图标、居中？） 其他补充 |
@isLinXu | |
| 参数与返回值的写法 | 参数格式、内容规范 返回值格式、内容规范 其他补充：如形状(shape) |
||
| 代码示例的写法 | 制定代码示例写作规范优秀示例解析 | ||
| API文档-提前预览 | 预览的价值，文档去哪里预览，怎么预览 可参考：[Beta]飞桨文档预览工具 |
||
| 常见异常情况 | 1. 源代码丢失 2. 示例代码：copy-from未成功 3. 出现warning & error 4. ... |
||
| 完整示例 | 中文API文档示例（常规，即function） 中文API文档示例（class） 英文API文档示例（常规，即function） 英文API文档示例（class） 可参考：PaddlePaddle/docs#5112 |
@Liyulingyue |
Metadata
Metadata
Assignees
Labels
Type
Projects
Status