企业官网建设流程全解析

• 科学计算
• 数据分析

本文以 NumPy 仓库中的 doc/EXAMPLE_DOCSTRING.rst 为范本，系统讲解 NumPy（乃至整个 SciPy 生态）docstring 的标准结构与写作方法。该文档以multivariate_normal随机分布函数为实例，逐节示范了从签名行、Parameters、Returns 到 References、Examples 的完整写法。读完本文，你将掌握如何为 C 语言扩展函数撰写带签名声明的 docstring、如何组织数学说明与可复现示例，并通过仓库中 numpy/random/mtrand.pyx 的真实实现与 numpy/random/tests/test_random.py 的测试用例，理解规范背后的工程实践。

文档定位：一份"活的"docstring 规范范例

doc/EXAMPLE_DOCSTRING.rst是 NumPy 仓库中一份特殊的文档——它不是讲述某个 API 的用法，而是用一整篇完整的 docstring来示范"如何写 docstring"。文档开篇的注释点明了两个关键事实：

1. 该示例针对的是C 语言编写（或经 Cython 编译）的函数，因此需要显式给出函数签名（signature）；
2. Python 无法通过内省（inspection）获取 C 函数的参数签名，所以签名必须写在 docstring 的首行；而对于其他用纯 Python 编写的函数，则直接从一行描述开始即可。

这意味着：凡是numpy/random/mtrand.pyx、numpy/random/_generator.pyx中定义的函数，其 docstring 都必须遵循这一约定——签名行 + 各规范小节。与之配套的写作规范可参考doc/HOWTO_DOCUMENT.rst（该文件已声明其内容被 numpydoc 文档标准取代，进一步印证了 NumPy docstring 规范的标准化地位）。

docstring 的标准结构：逐节剖析

范例 docstring 采用 numpydoc 约定，按固定顺序组织以下小节：

1. 签名行（Signature）

multivariate_normal(mean, cov[, shape])

签名行是 C 函数 docstring 的第一行，用于弥补 Python 无法内省 C 函数签名的缺陷。注意示例中使用了方括号[, shape]表示可选参数——这是旧式写法；在仓库真实代码中，签名已显式写出全部参数与默认值，例如 numpy/random/mtrand.pyx 中的：

multivariate_normal(mean, cov, size=None, check_valid='warn', tol=1e-8)

显然，显式列出默认值比方括号省略写法更精确、更利于文档工具解析。

2. 一句话描述（Summary）

签名之后紧跟一行式描述，说明函数做什么：

Draw samples from a multivariate normal distribution.

规范要求：这一行要短、以动词开头、能独立成句，让读者在文档索引中即可快速理解函数用途。后续的详细段落则进一步展开背景，例如将多元正态分布定义为"一维正态分布向高维的推广"，并类比 mean 与方差的关系。

3. Parameters 小节

示例给出三个参数：

真实代码中的参数列表更为完整，numpy/random/mtrand.pyx 补充了：

• cov增加约束说明："必须对称且半正定才能正确采样"；
• size : int or tuple of ints, optional，明确标注size=None时返回单个(N,)样本；
• check_valid : { 'warn', 'raise', 'ignore' }, optional——协方差矩阵非半正定时采取的行为；
• tol : float, optional——检查协方差奇异值时的容差，且注明"检查前cov会被转换为 double"。

而新的Generator版本（numpy/random/_generator.pyx）还多了method : { 'svd', 'eigh', 'cholesky' }, optional参数，用于选择计算因子矩阵A（满足A @ A.T = cov）的分解方法，并明确性能差异：默认'svd'最慢但最稳健，'cholesky'最快但稳健性较差，'eigh'介于两者之间。

4. Returns 小节

out : ndarray The drawn samples, arranged according to `shape`. ...

规范要求：即使返回值类型简单，也要写出out : ndarray及其形状语义。示例特别解释了输出形状规则——out[i, j, ... , :]的最后一维是 N 维样本，即每个切片out[i, j, ...]都是来自该分布的一个 N 维采样值。

5. See also 小节

用于给出"相关但不等同"的参考对象：

normal scipy.stats.norm : Provides random variates, as well as probability density function, cumulative density function, etc.

规范的写法是：同类 API 直接列名称，跨模块对象采用module.object : 一句话说明的格式。仓库真实 docstring 中则将random.Generator.multivariate_normal列为首选参考，并标注"新代码应使用"该新 API。

6. Notes 小节：数学背景与几何直觉

Notes 是 docstring 中最具技术含量的小节，范例展示了三方面内容：

• 数学定义：均值是 N 维空间中样本最可能生成的位置坐标，类比一维钟形曲线的峰值；协方差矩阵元素C_ij是x_i与x_j的协方差，C_ii是x_i的方差（"散布程度"）。原文使用 reStructuredText 数学指令:math:排版公式。
• 常用近似模型：球面协方差（cov为单位阵的倍数）与对角协方差（cov仅对角线上有非负元素）——这是实际应用中降低参数量的两种常见做法。
• 可运行的绘图示例：用对角协方差[[1, 0], [0, 100]]生成 5000 个点并绘制散点图，直观展示"点在 x 轴或 y 轴方向延展"的几何特性（注意此时两变量独立、等高线方向与坐标轴对齐）。

7. References 小节

列出支撑数学背景的文献，使用.. [n]编号列表格式：

.. [1] A. Papoulis, "Probability, Random Variables, and Stochastic Processes," 3rd ed., McGraw-Hill Companies, 1991 .. [2] R.O. Duda, P.E. Hart, and D.G. Stork, "Pattern Classification," 2nd ed., Wiley, 2001.

仓库真实 docstring（numpy/random/mtrand.pyx）保留了这两条引用，说明教学范例与实际实现一脉相承。

8. Examples 小节：可复现的 doctest

Examples 必须是可以直接被 doctest 执行的代码，范例演示了两种用法：

>>> mean = (1, 2) >>> cov = [[1, 0], [0, 1]] >>> x = np.random.multivariate_normal(mean, cov, (3, 3)) >>> x.shape (3, 3, 2)

即size=(3, 3)时生成 3×3 个二维样本，输出形状为(3, 3, 2)。第二个示例则展示"结果因随机数而异"的写法——用# may vary标注不确定性输出。真实 docstring 还加入了统计验证示例：生成 800 个样本后，用pts.mean(axis=0)、np.cov(pts.T)、np.corrcoef(pts.T)验证样本均值、协方差与相关系数接近理论值，并附散点图展示负相关点云的取向。

9. 索引指令（index）

docstring 末尾的：

.. index: :refguide: random:distributions

将本函数纳入文档索引的random:distributions分类，便于文档工具生成交叉引用与 API 索引。

从范例到实现：multivariate_normal 的源码级原理

范例 docstring 描述的 API 在仓库中的实现位于 numpy/random/mtrand.pyx。其采样算法值得关注（注释中已完整阐述）：

1. 预处理：mean、cov转为 ndarray 并做维度校验（mean 必须一维、cov 必须二维且方阵、两者长度一致），否则抛出ValueError；
2. 生成标准正态矩阵：按final_shape = list(shape) + [N]生成独立标准正态随机数并 reshape 为(-1, N)；
3. SVD 分解求因子矩阵：对cov做svd(cov)得(u, s, v)，由于sqrt(s) * v满足A @ A.T == cov（即dot(transpose(A), A) == cov），于是x = np.dot(x, np.sqrt(s)[:, None] * v)即可将标准正态样本变换为具有目标协方差的多元正态样本；
4. 平移与整形：x += mean并 reshape 回final_shape。

代码注释特别说明：选择 SVD 而非 Cholesky 是为了保持历史输出结果一致（GH10839确保先cov.astype(np.double)再比较，使tol有意义）。check_valid的实现也清晰可循：非'ignore'时用np.allclose(np.dot(v.T * s, v), cov, rtol=tol, atol=tol)判断协方差是否半正定，不满足时按'warn'发RuntimeWarning、按'raise'抛ValueError。这正对应 docstring 中check_valid参数的三档语义，Docstring、实现与文档三者完全一致。

测试用例对 docstring 的印证

numpy/random/tests/test_random.py 中的test_multivariate_normal逐一验证了 docstring 声称的行为：

• size=(3, 2)时输出形状与数值序列完全吻合（与期望数组比较，精度decimal=15）；
• 不传 size（默认单样本）时返回(N,)形状——印证 Returns 中"未指定 shape 时返回单个 N 维样本"的说明；
• 非半正定协方差[[1, 2], [2, 1]]触发RuntimeWarning——印证check_valid='warn'默认行为；
• check_valid='ignore'时不产生任何警告；
• check_valid='raise'时抛出ValueError；
• float32 协方差输入也能正常采样且不触发异常——印证实现中的 double 转换逻辑。

新旧 API 与写作规范的最佳实践

从范例文档到仓库实现，可以总结出 NumPy docstring 写作的核心最佳实践：

1. 签名行只属于 C/Cython 函数；纯 Python 函数直接从一句话描述开始；
2. 小节顺序固定：Signature → Summary → Parameters → Returns → See also → Notes → References → Examples → 索引指令，便于工具链（Sphinx + numpydoc）自动解析；
3. 参数与返回描述要给出形状与约束（如(N,) ndarray、"必须对称半正定"），并标注可选参数默认值；
4. 数学内容用:math:排版，复杂背景放入 Notes，避免挤占 Summary；
5. Examples 必须可运行，随机结果用# may vary标注；示例不仅要展示调用，更要展示如何验证结果（均值、协方差的统计核对）；
6. 文档、实现、测试三方对齐：docstring 中的每个参数与行为，都能在 numpy/random/mtrand.pyx、numpy/random/_generator.pyx 与numpy/random/tests/下的测试中找到对应证据。

撰写 NumPy 风格 docstring 时，把doc/EXAMPLE_DOCSTRING.rst作为起点模板，对照真实实现补齐参数细节（如check_valid、tol、method），并用仓库测试验证示例结论，即可写出信息完整、机器可解析、读者可复现的高质量 API 文档。

• 科学计算
• 数据分析