[Docs]飞桨 API 文档体验提升计划

[Ligoml]

用于跟踪 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

[Liyulingyue]

认领task
完整示例

[whisky-12]

路线一：API文档问题修复 怎么填写认领信息？

[Ligoml]

路线一：API文档问题修复 怎么填写认领信息？

回复issue就可以啦

[enkilee]

修复broadcasting说明的超链接失效问题：
PaddlePaddle/docs#5441

[Lemon-er]

路线一：API文档问题修复
题目：[DenseTensor 概念统一]
认领人：Lemon-er

[ZhangYuef]

• 路线一：API文档问题修复
• 题目：对inplace api增加介绍信息
• 认领人：ZhangYuef

---

PR: PaddlePaddle/docs#5469

[enkilee]

#48283 关了无法打开了。重修了英文的boardcasting：#48434

[lizechng]

路线一：API文档问题修复
题目：在英文API文档中统一静态图模式与动态图模式的英文翻译
认领人：lizechng

[Atlantisming]

路线一：API文档问题修复
题目：在中文API文档中统一 Tensor 的描述
认领人：Atlantisming

[whisky-12]

路线一：API文档修复
题目：对与超链接没有生成的情况，进行全量检索与修复
认领人：魔术师

[isLinXu]

路线二：飞桨API文档写作规范手册制定
题目：其他规范(作图规范)
认领人：isLinXu
提交：PaddlePaddle/docs#5497

[jjyaoao]

路线一：API文档问题修复
题目：处理API文档中的死链问题
认领人：jjyaoao

[tianxingxia-cn]

路线一：API文档问题修复
题目：对与超链接没有生成的情况，进行全量检索与修复
认领人：tianxingxia-cn
提交：PaddlePaddle/docs#5521

[sanbuphy]

路线一：API文档问题修复
题目：1 在中文API文档中统一 Tensor 的描述 2 在英文API文档中统一静态图模式与动态图模式的英文翻译 3 示例代码中移除第三方库numpy
认领人：sanbuphy

[DrRyanHuang]

路线二：飞桨API文档写作规范手册制定
题目：数字及数学公式的写法
认领人：Ryan

[Atlantisming]

路线一：API文档问题修复
题目：在英文API文档中统一静态图模式与动态图模式的英文翻译
认领人：Atlantisming

[luotao1]

小结：基于docs-sig的全量API文档（1005组）评估结论，对需要优化的594组文档进行重点修正，完成336组API中英文文档优化，本年度共计完成74.3%的API文档优化工作，并完成了示例代码中移除第三方库numpy、DenseTensor概念统一、修复API文档中的死链问题与编译报错、Tensor与动静态图描述统一等9项重点任务。