飞桨 API 文档的不规范之处及其规范化方案汇总

[BrilliantYuKaimin]

我在 PaddlePaddle/Paddle#43656 中提出了关于完善飞桨 API 文档写作标准的 Roadmap。这个 Issue 会先以评论的形式记录飞桨 API 文档中的各类不规范之处及其规范化方案，待其覆盖方面到达一定程度后再整理汇总成一份完整、正规的 API 文档写作规范。👏欢迎有兴趣的同学加入进来！

已经提出的点

• 一元数学函数类 API 的统一写法
• 外国人名的处理
• 一些五花八门的符号的用法的统一
• 标点符号问题
• 代码、字面量等特殊内容的表现形式

[BrilliantYuKaimin]

一元数学函数类 API 的统一写法

按理说 paddle.sin 和 paddle.cos 的文档是只有“正”和“余”两个字的区别的，但目前它们的写法却完全不同。事实上，这类一元数学函数的 API 文档可以有一个统一写法。这里以 paddle.erf 为例给出一个一元数学函数 API 的写法示例。

erf

paddle.erf(x, name=None)

误差函数。具体地，对 Tensor x 中的每个元素 $x$ 计算
$$\mathrm{erf}(x)=\dfrac{1}{\sqrt{\pi}}\int_{-x}^x\mathrm e^{-t^2}\,\mathrm dt,$$
其中 $\mathrm e$ 是自然对数的底。误差函数 $\mathrm{erf}(x)$ 的函数图像如下图所示。

参数

• x (Tensor) - 误差函数的输入。数据类型为 float16、float32 或 float64。
• name (str，可选) - 具体用法请参见 Name，一般无需设置，默认值为 None。

返回

Tensor，数据类型和形状与 x 一致。

代码示例

import paddle
x = paddle.to_tensor([-0.4, -0.2, 0.1, 0.3])
out = paddle.erf(x)
print(out)
# [-0.42839236 -0.22270259  0.11246292  0.32862676]

写作要点有

• 给出这个函数的中文名称和计算公式。
• 对于高中范围以外的函数给出其函数图像（上面给出的图像只是一个示例，具体的绘图风格和插入方式还有待商榷）。
• 参数 x 的解释同一写为某某函数的输入。

[BrilliantYuKaimin]

外国人名的处理

在正规的中文环境中，外国人名一律应当翻译。然而飞桨 API 中文文档中几乎都没有译出人名，甚至连中国人名也使用拼音（paddle.nn.PixelShuffle、paddle.nn.initializer.KaimingNormal）。在 docs·wiki 下的深度学习常用术语表对人名的处理也十分不统一，比如把 Gibbs steps 译为了吉布斯步数而 Gibbs Sampling 却译为 Gibbs 采样。

事实上大多数人不能正确读对外国人名，比如 Galois (/ɡælˈwɑː/) 和 Euler (/ˈɔɪlər/)。所以将人名译为汉语才能有利于交流。基本规则为：汉字文化圈（日本、韩国、朝鲜等）的人名按其汉字写法翻译，非汉字文化圈国家的人名按各国语言的发音来翻译。大多数学者的中文名可以在互联网上找到，若他有中文维基百科，则使用维基百科上的译名。

[BrilliantYuKaimin]

一些五花八门的符号的用法的统一

符号内容	候选	建议	建议理由	备注
Tensor 形状表示	$[N,C,H,W]$、 $(N,C,H,W)$ 、[N,C,H,W]、(N,C,H,W)	$[N,C,H,W]$	形状各分量的值大概率在后文还会出现在数学公式中。若使用圆括号，一维 Tensor 的形状要写成 $(N,)$，不好看。
多维 Tensor 的说法	$n$-D Tensor、 $n$ 维 Tensor	$n$ 维 Tensor	少一个连字符可以减少写错的可能（使用了全角的连字符、连字符放在了公式内）。	若 $n$ 是具体的数，这个数也要放到公式环境，比如「 $4$ 维 Tensor」。
数据类型的描述	「数据类型为：int32、int64、float32、float64」「数据类型为：int32、int64、float32 或 float64」「数据类型为 int32、int64、float32 或 float64」	数据类型为 int32、int64、float32 或 float64	更像一个自然的句子。	还应当为所有的数据类型排个序。
	list(int)、list[int]、list of int	list[int]	与 Python 中的类型提示（Type Hints）保持一致。
未完待续

[BrilliantYuKaimin]

标点符号问题

在中文文档中应该使用全角标点符号，但有三个地方例外：

• 参数

  x (list|Tensor) - 输入。

中的 (、)、| 和 -

• 数学公式中的标点符号
• 代码中的标点符号

中文标点符号的用法参考这里。

关于使用全角句点的建议

在中文科技文排版中一般会使用全角的「．」而不是「。」。因为当行间公式作为句子的结束时句号需要放在公式内部，比如

著名的欧拉公式为
$$\exp(\mathrm ix)=\mathrm e^{\mathrm{i}x}=\cos x+\mathrm i\sin x.$$

于是用「．」代替「。」可以让所有的句号在视觉效果上达到一致。

[BrilliantYuKaimin]

代码、字面量等特殊内容的表现形式

当我们提到 API 的某个参数时，我们应该把它放在一个行内代码块中，像 x 这样。根据这里的讨论，rst 中的 ``x`` 和 :attr:`x` 是可以渲染出不同的效果的，目前飞桨文档的前端没有对此作区分，所以大多数开发者没有注意到这两者区别。为了将来调整前端渲染样式后能区分表示参数名的代码块，在文档的源文件中应当用 :attr:`x` 这样的形式来表示一个参数。

另外，在解释 API 参数的含义时，也会经常提到 None、True、False、1.0 等编程语言中的字面量，以及 Tensor、int、int32 等表示类型的词。这些内容在飞桨文档中的展现形式还没有统一，有行内代码块、纯文本和斜体形式。根据 @SigureMo 的调研，像 :attr:`x` 这样的形式在 rst 中叫做 role，而 Sphinx 支持自定义 role。于是我们计划为下面这几类的内容分别定义 role，以便在前端展示出不同的效果：

• 表示字面量的内容，如 None、True、1.0、'NCHW'
• 表示类型的内容，如 Tensor、int、int32、paddle.dtype