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

[BrilliantYuKaimin]

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

已经提出的点

• 一元数学函数类 API 的统一写法
• 外国人名的处理
• 一些五花八门的符号的用法的统一
• 标点符号问题
• 代码、字面量等特殊内容的表现形式
• 参数可选值详情以列表的形式展开
• 数学公式的写法
• API 文档在 IDE 环境中的展示

[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	更像一个自然的句子。	还应当为所有的数据类型排个序。
数据类型的英文描述	The/It's data type is/should be/can be int32, int64, float32 or/and float64
默认值的描述	「默认值为 True」「默认为 True」「默认值：True」	默认值为 True	更像一个自然的句子。
默认值的英文描述	「The default is True」「Default is True」「Default value is True」「Default: True」
	list(int)、list[int]、list of int	list[int]	与 Python 中的类型提示（Type Hints）保持一致。
未完待续

[SigureMo]

可以添加默认值的描述作为一项，因为现有文档里有的是 默认值为 xxx，有的是 默认值：xxx，建议前者，同「数据类型的描述」中的理由

英文可能也要类似的内容

[SigureMo]

在表示区间的时候也应当使用 math 环境～

[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

[SigureMo]

参数可选值详情以列表的形式展开

很多参数会有多个可选值，但是目前在展示可选值的意义的时候经常是写在一行里的，比如 SmoothL1Loss（正在 #5211 修改，可能过两天这个就改了），个人认为展示可选值最好是直接写成列表的形式，每个可选值作为一个列表项，这里有一个前两天 #5136 刚改好的例子 Pad1D，个人认为这样会比较清晰，可选值都有哪些一目了然。（一些前置的探讨也可以见 #5136）

因此建议有可选值的参数采用以下格式：

- a (str, optional): 一段描述。可选值为 ``'x'``、``'y'`` 或 ``'z'``，默认值为 ``'x'``。

   - ``'x'`` 表示 xxx；
   - ``'y'`` 表示 yyy；
   - ``'z'`` 表示 zzz。

- b (str, optional): xxxx。

Note

• 当可选值不需要对各个参数解释详细意义的时候，当然不需要按照本格式书写。
• 嵌套列表上下必须各空一行，参考 reStructuredText Primer，否则会解析为 <dl>
• 嵌套列表缩进空格数 >= 3，2 个空格或者 1 个空格无法正常识别为嵌套列表

可能存在的争议点：

• 是否需要展开成列表（本规范是否有必要）；
• 默认值为是紧随第一句之后，还是在所有可选值意义都展示完，在列表之后展示，如下所示。

- a (str, optional): 一段描述。可选值为 ``'x'``、``'y'`` 或 ``'z'``。

   - ``'x'`` 表示 xxx；
   - ``'y'`` 表示 yyy；
   - ``'z'`` 表示 zzz。

   默认值为 ``'x'``。

- b (str, optional): xxxx。

[BrilliantYuKaimin]

在需要详细解释各值的含义时展开成列表会清晰很多。下面是我建议的写法：

- a (str, optional): 一段描述。可选值有

   - ``'x'``，表示 xxx；
   - ``'y'``，表示 yyy；
   - ``'z'``，表示 zzz。

   默认值为 ``'x'``。

- b (str, optional): xxxx。

[SigureMo]

我觉得可以，刚刚我尝试了下，格式上的话

- a (str, optional): 一段描述。可选值有
.. 本行必须加
   - ``'x'``，表示 xxx；
   - ``'y'``，表示 yyy；
   - ``'z'``，表示 zzz。
.. 本行必须加
   默认值为 ``'x'``。
.. 本行可加可不加
- b (str, optional): xxxx。

默认值那行下面空行是可加可不加的，也就是说只有嵌套列表需要强制上下各空一行

[BrilliantYuKaimin]

数学公式的写法

尽量不使用单词作为公式中的变量名

很多 API 的参数名就是某个希腊字母的英文，比如 alpha、beta 和 delta。目前的 API 文档中往往在公式中直接写出 $alpha$、 $beta$ 和 $delta$ 这样的内容。在公式中，我们完全可以将其写成 $\alpha$、 $\beta$ 和 $\delta$（\alpha、\beta 和 \delta）。这样我们在后面解释 alpha 这个参数时就可以直接说它是公式中的 $\alpha$，简洁明了。

像 kernel_size 这样的参数名，当需要在公式中提到它时，也建议用一个字母表示。可以这样说：

把 kernel_size 的值记成 $k$。

若在特殊情况下必须在公式中出现一个单词，则应当使用打字机字体，比如 $\texttt{kernel\_size}$（\texttt{kernel\_size}）。

特殊函数、特殊常数应该使用正体

像三角函数、反三角函数、对数函数这些「特殊函数」，应当使用正体，写成 $\sin x$、 $\ln x$、 $\log_2x$、 $\arcsin x$。它们在 LaTeX 中的写法是 \sin x、\ln x、\log_2x、\arcsin x。对于 LaTeX 中没有提供的函数，比如符号函数 $\mathrm{sgn}\,x$，我们应当手动加正：\mathrm{sgn}\,x。注意这里的 \, 表示八分之一个空格，在 $x$ 外面有括号包裹的情况下是不需要的： $\mathrm{sgn}(x)$（\mathrm{sgn}(x)）。

自然对数的底 $\mathrm e$ 和虚数单位 $\mathrm i$ 也需要使用正体：\mathrm e、\mathrm i。

分段函数的写法

下面是把绝对值函数写成分段函数的例子：
$$|x|=\begin{cases}x,&x\geqslant0;\\-x,&x<0.\end{cases}$$
对应的 LaTeX 代码为

|x|=\begin{cases}
    x,&x\geqslant0;\\
    -x,&x<0.
\end{cases}

其中的标点符号是需要注意的。

未完待续

[jzhang533]

API文档在IDE环境中的展示

现在我们考虑的主要是API文档在网页端的展示。另外一个很重要的展示API文档的渠道是，在程序员使用的IDE环境中。
例如在jupyter notbook中，输入?paddle.jit.save，在python交互环境中输入help(paddle.jit.save)，显示出来的这个API的文档是空的（虽然没有做测试，但我想，在PyCharm中，应该也是空的）。但在网页中，是有这个API的文档的。类似的API应该还有一些。

API文档在这些IDE环境中，应该也是需要正常能展示出来的。

[SigureMo]

只看 paddle.jit.save 的话，主要问题应该是为其装饰的一个装饰器没有保持其原有属性，导致 __doc__ 属性丢失，因此无论是 help 函数、还是 Jupyter Notebook 都无法获取其 docstring，英文文档网页中虽然有该页面，却没有内容，不过 PyCharm 和 VS Code（languageServer=Jedi）却是可以正常获取的。

我在 PaddlePaddle/Paddle#45773 修改了下其中一个装饰器，使其也能够保持原有 __doc__ 属性，经过测试 __doc__ 已经可以获取，并且 Jupyter Notebook 和 help 函数也是正常显示结果，英文文档不确定是否正常，但大概是正常的

[jzhang533]

我们曾经维护过一个常见文档的写法的模板，但后来不再更新了：https://github.com/PaddlePaddle/docs/blob/develop/docs/templates/common_docs.py 。

也许我们可以维护一份常见文档的写法，并推广使用。

[SigureMo]

文档格式规范

这里用于记录和讨论文档格式规范

• 缩进
  • reStructureText 文档统一采用 4 缩进（使用 4 个空格作为一级缩进）
  • Markdown 文档待定（候选：2、3、4）

其它内容待定

---

关于缩进的统计

• Markdown，可通过在全 GitHub 搜索 .editorconfig 文件中包含 md 字段的配置中统计（https://cs.github.com/?scopeName=All+repos&scope=&q=path%3A.editorconfig+md ，GitHub Code Search 好像还在测试阶段，这个链接可能打不开）