【PFCC-Roadmap】完善 API 文档写作标准 #43656
Description
Roadmap
飞桨中文文档托管在 PaddlePaddle/docs 仓库下，相关的贡献指南在 https://github.com/PaddlePaddle/docs/wiki ，其中的《飞桨 API 文档书写规范》是内容方面的规范，而《飞桨文档写作规范》是格式方面的规范。虽然有这些规范在，但现在的飞桨 API 文档还存在大量的不规范之处，包括标点误用、语病、公式不规范等。本 Roadmap 旨在完善飞桨 API 文档写作标准，为文档方向的 Roadmap 提供基石，从而使飞桨 API 文档达到出版物的标准。
【目标】（包括但不限于）
一、 规范标点符号的使用（全角与半角的区分、逗号与顿号的区分、冒号的用法等）。
二、 明确何时使用灰色底块效果、何时使用公式、何时使用一般效果，即 x、$x$ 和 x 的区别。
三、 对同一类 API 制定相同的描述方式。比如 paddle.sin 的描述是
计算输入的正弦值。
而 paddle.cos 的描述是
余弦函数。
输入范围是 (-inf, inf)，输出范围是 [-1,1]。
$$ out=cos(x) $$
（摘录于 2022 年 6 月 17 日）
四、 规范数学公式的使用，包括但不限于
- 合理地使用行间公式（比如上面 paddle.cos 的描述中的公式很短，没必要单独成行）；
- 行间公式的标点；
- 公式不能孤立地出现（比如上面 paddle.cos 的描述中公式就是孤立地出现的）；
- 正体、斜体、粗体的区别（比如上面 paddle.cos 的描述中应当用
$\cos$ 而不是$cos$ ）。
五、 规范外文人名的处理方法。
六、 进一步完善当前《飞桨 API 文档书写规范》中的各项条目。
【参考资料】
-
新华通讯社译名室. 世界人名翻译大辞典:a comprehensive dictionary of names in Roman-Chinese-第2版[M]. 中国对外翻译出版公司, 2007.