为 SciPy 文档做贡献#

我们很乐意收到关于文档缺陷的反馈并进行修复。但要解决最棘手的问题，我们有时不得不推迟或忽略一些 bug 报告。以下是值得重点关注的缺陷。

技术性不准确是最高优先级——文档字符串缺少参数、函数/参数/方法的描述有误等等。其他“结构性”缺陷，如链接错误，也获得优先处理。所有这些修复都易于确认和实施。如果你知道如何操作，可以提交一个包含修复的拉取请求 (PR)；否则，请打开一个 issue。

拼写和语法错误的优先级较低；我们欢迎关于它们的反馈，但可能无法及时修复。这些也可以通过拉取请求或 issue 来处理。

明显的措辞错误（如遗漏“not”）属于拼写错误类别，但其他措辞修改——即使是为了语法——也需要权衡，这会提高门槛。人们可以想象一些情况，其中“修复”是否应该进行并不清楚，例如：

  • 试图“修复”牛津逗号的所有用法（或未使用）。

  • 常用用法正确性正在演变的情况，例如“comprised of”

最容易接受的修复是那些原文清晰且明确错误的修复；需要细微编辑判断的更改最好避免。（但请注意，这并不是关于更新文档以修复令人困惑的陈述或处理用户报告的文档问题。）

注意

作为一般指导，尽量累积小的文档更改（如拼写错误），而不是逐个发送。在可能的情况下，还要确保使用正确的命令跳过 CI 检查文档更改。

用 C 或 Fortran 扩展模块中定义的一些函数/对象，它们的文档字符串与实际代码是分开定义的。请务必使用 grep 或其他类似工具搜索您正在查找的函数文档字符串。

使用 Sphinx 本地渲染文档#

SciPy 的文档字符串使用 Sphinx 和 PyData Sphinx 主题渲染为 HTML。文档字符串的编写在 文档风格中有介绍；本文档解释了如何检查文档字符串是否正确渲染。

有关视频教程，请参阅 使用 Sphinx 渲染 SciPy 文档。

在您自己的计算机上渲染文档

  1. 确保您有一个可用的 SciPy 构建（请参阅 从源代码构建）。

  2. 然后运行 spin docs 来构建文档。第一次构建可能需要一些时间，但后续的文档构建通常会快得多。

  3. 在 doc/build/html/ 中查看文档。您可以从 index.html 开始浏览，也可以直接跳转到您感兴趣的文件。

注意

  • 某些文档的更改在 Sphinx 文档重新构建时不会生效。在这种情况下，您可以通过删除目录 scipy/doc/build 和 source/reference/generated 来从头开始构建，或者运行 spin docs clean 然后再次构建文档。

  • 如果上述命令找到的 SciPy 版本与仓库中最新提交的版本不同，您将看到类似以下的消息：

    installed scipy 5fd20ec1aa != current repo git version '35fd20ec1a'

    这表明您很可能正在使用错误的 SciPy 安装，请使用 python -c "import scipy; print(scipy.__file__)" 进行检查。

  • SciPy 文档包含使用 jupyterlite-sphinx 扩展渲染的交互式示例。有关更多详细信息，请参阅 将 Jupyter notebook 添加或编辑为教程 和 文档字符串中的交互式示例。

在云端检查文档#

一旦打开 PR，您就可以在云端检查文档是否正确渲染。

  1. 登录 GitHub。

  2. 使用您的 GitHub 帐户登录 CircleCI。

  3. 回到 GitHub，在 PR 的底部，选择“显示所有检查”。

  4. 在“在此处检查渲染的文档！”旁边，选择“详细信息”。

文档指南#

使用“必须”，而不是“应该”#

当指定输入参数的必要条件时，“必须”比“应该”更可取。对于许多英语母语者来说，“必须”意味着比“应该”更强的约束，例如“我必须有氧气才能生存”与“我应该多运动”。

是

Parameters
----------
x : float
    `x` must be nonnegative.

否

Parameters
----------
x : float
    `x` should be nonnegative.

使用 ‘versionadded’ 标记#

  • 对于新函数，‘versionadded’ 标记应放在“Notes”部分，而不是文档字符串开头的描述中。

  • 对于添加到现有函数的新参数，‘versionadded’ 标记应放在“Parameters”部分的参数描述末尾。

在“References”部分引用维基百科文章#

使用维基百科文章作为参考文献是可以接受的。在创建参考文献的引用时，请包含文章标题，“Wikipedia”名称（类似于给出期刊名称），以及 URL。

是

.. [1] "Zeta Distribution", Wikipedia,
       https://en.wikipedia.org/wiki/Zeta_distribution

否

.. [1] https://en.wikipedia.org/wiki/Zeta_distribution

参考文献中的 DOI#

强烈建议在参考文献中使用 DOI。Sphinx 为 DOI 提供了特殊的语法：:doi:。例如：

.. [2] D. Fishkind, S. Adali, H. Patsolic, L. Meng, D. Singh, V. Lyzinski,
       C. Priebe, "Seeded graph matching", Pattern Recognit. 87 (2019):
       203-215, :doi:`10.1016/j.patcog.2018.09.014`

(arXiv 文章也有特殊的标记可用：:arxiv:。)

项目符号列表#

这与其说是一个指导方针，不如说是对项目符号列表 Sphinx 标记的提醒。缩进不正确的使用足够普遍，以至于值得在此提及。

创建项目符号列表时

  • 不要在前一行以 :: 结尾。

  • 不要缩进项目符号。

  • 在列表前后包含一个空行。

一些例子

是

Some text that precedes this interesting list:

* The first item in the list.
* The second item in the list.
* You get the idea.

Some text that follows the list.

否

Some text that precedes this interesting list:

  * The first item in the list.
  * The second item in the list.
  * You get the idea.

Some text that follows the list.

否

Some text that precedes this interesting list:
* The first item in the list.
* The second item in the list.
* You get the idea.
Some text that follows the list.

自包含的示例#

每个“Example”部分（包括文档字符串和通用文档）都必须是自包含的。这意味着所有导入都必须显式，使用的数据必须已定义，并且代码在复制粘贴到新的 Python 解释器中时应该“直接工作”。

是

>>> import numpy as np
>>> rng = np.random.default_rng()

否

>>> rng = np.random.default_rng()

可以（也推荐）将代码块与解释穿插。代码块和解释性文本之间必须用空行分隔。

是

Some initial text

>>> import numpy as np
>>> rng = np.random.default_rng()

This is some explanation

>>> rng.random(10)

示例和随机性#

在持续集成 (CI) 套件中，示例会被执行，输出会与提供的参考进行比较。主要目标是确保示例是正确的；失败会提醒我们示例可能需要调整（例如，因为 API 自编写以来已发生更改）。Doctests 无意用作底层实现的单元测试。

如果需要随机数生成器，必须使用 np.random.Generator。创建 NumPy Generator 的规范方法是使用 np.random.default_rng。

是

>>> import numpy as np
>>> rng = np.random.default_rng()
>>> sample = rng.random(10)

是

>>> import numpy as np
>>> rng = np.random.default_rng(102524723947864966825913730119128190984)
>>> sample = rng.random(10)

否

>>> import numpy as np
>>> sample = np.random.random(10)

设置生成器对象的种子是可选的。如果使用种子，请避免使用常用数字，而是使用 np.random.SeedSequence().entropy 生成种子。如果不提供种子，在执行 doctests 时使用的默认值为 1638083107694713882823079058616272161。无论哪种情况，渲染的文档都不会显示种子。目的是阻止用户在代码中复制粘贴种子，而是让他们在程序中使用种子时做出明确的决定。其后果是用户无法完全重现示例的结果，因此使用随机数据的示例不应引用基于随机数据的精确数值，也不应依赖它们来达到其目的。

遗留指令#

如果一个函数、模块或 API 处于遗留模式，意味着它被保留以实现向后兼容，但不推荐在新代码中使用，您可以使用 .. legacy:: 指令。

默认情况下，如果不带参数使用，遗留指令将生成以下输出：

旧版

此子模块被视为遗留模块，将不再接收更新。虽然我们目前没有计划将其移除，但我们建议新代码使用更现代的替代方案。

我们强烈建议您也添加一个自定义消息，例如一个新 API 来替换旧的 API。此消息将附加到默认消息之后：

.. legacy::

   New code should use :mod:`scipy.fft`.

将生成以下输出：

旧版

此子模块被视为遗留模块，将不再接收更新。虽然我们目前没有计划将其移除，但我们建议新代码使用更现代的替代方案。新代码应使用 scipy.fft。

最后，如果您想引用一个函数、方法（或任何自定义对象）而不是一个子模块，您可以使用一个可选参数：

.. legacy:: function

这将生成以下输出：

旧版

此函数被视为遗留函数，将不再接收更新。虽然我们目前没有计划将其移除，但我们建议新代码使用更现代的替代方案。

—