贡献 SciPy 文档#

我们很乐意听到并修复文档缺陷。但是，为了解决最大的问题，我们最终不得不推迟或忽略一些错误报告。以下是要解决的最佳缺陷。

最高优先级是**技术上的不准确** – docstring 中缺少参数，函数/参数/方法的错误描述等等。其他“结构性”缺陷（如损坏的链接）也具有优先级。所有这些修复都易于确认和实施。如果您知道如何操作，可以提交一个 pull request (PR) 进行修复；否则，请打开一个 issue。

**拼写错误和笔误**的优先级较低；我们欢迎听到这些问题，但可能无法及时修复。这些也可以作为 pull request 或 issue 处理。

明显的**措辞**错误（例如遗漏了“not”）属于拼写错误类别，但其他改写 – 即使是为了语法 – 也需要做出判断，这提高了门槛。可以想象一些情况下，不清楚是否应该进行“修复”，例如

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

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

最容易接受的修复是那些原始版本明显且明确错误的地方；需要微妙的编辑判断的更改最好避免。（但请注意，这与更新文档以修复用户报告的令人困惑的陈述或以其他方式处理文档问题无关。）

注意

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

在 C 或 Fortran 扩展模块中定义的一些函数/对象，它们的 docstring 与实际代码分开定义。确保使用 grep 或其他类似工具搜索您要查找的函数 docstring。

使用 Sphinx 在本地渲染文档#

SciPy docstring 使用 Sphinx 和 PyData Sphinx 主题 渲染为 HTML。编写 docstring 在 文档样式 中介绍；本文档解释了如何检查 docstring 是否正确渲染。

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

要在您自己的机器上渲染文档

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

  2. 然后运行 python dev.py doc 来构建文档。第一次可能需要一段时间，但随后的文档构建通常会快得多。

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

注意

  • 当重建 Sphinx 文档时，对某些文档的更改不会生效。在这种情况下，您可以从头开始构建，方法是删除目录 scipy/doc/build 和 source/reference/generated，或者运行 python dev.py doc clean 然后再次构建文档。

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

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

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

  • SciPy 文档包含在 jupyterlite-sphinx 扩展的帮助下渲染的交互式示例。有关更多详细信息，请参阅添加或编辑 Jupyter notebooks 教程 和 docstring 中的交互式示例。

在云上检查文档#

打开 PR 后，您可以检查文档是否在云上正确渲染。

  1. 登录到GitHub。

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

  3. 返回 GitHub，在 PR 的底部，选择“Show all Checks”。

  4. 在“Check the rendered docs here!”旁边，选择“Details”。

文档指南#

使用 “must”，而不是 “should”#

当指定输入参数的必需条件时，单词 “must” 比 “should” 更可取。对于许多说英语的人来说，“must” 比 “should” 意味着更强的约束，例如 “I must have oxygen to live” 与 “I should exercise more”。

正确

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

错误

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

使用 ‘versionadded’ 标记#

  • 对于一个新函数，‘versionadded’ 标记放在 “Notes” 部分，而不是在 docstring 开头的描述中。

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

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

可以接受使用维基百科文章作为参考。在创建引用的 citation 时，包括文章标题、“Wikipedia” 名称（类似于给出期刊标题的方式）和 URL。

正确

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

错误

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

参考文献中的 DOI#

强烈建议在参考文献中使用 DOI。DOI 有特殊的 Sphinx 语法：: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” 部分（在 docstring 和一般文档中）都必须是独立的。这意味着所有导入都必须是显式的，使用的数据必须被定义，并且代码在复制粘贴到新的 Python 解释器中时应该 “just work”。

正确

>>> 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 自编写以来发生了变化）。Doctest 不应被用作底层实现的单元测试。

如果需要随机数生成器，则必须使用 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 生成种子。如果没有提供种子，则在执行 doctest 时使用默认值 1638083107694713882823079058616272161。无论哪种情况，渲染的文档都不会显示种子。目的是阻止用户在其代码中复制/粘贴种子，而是明确决定在其程序中使用种子。结果是用户不能完全重现例子的结果，因此使用随机数据的例子不应参考基于随机数据的精确数值或依赖它们来表达他们的观点。

Legacy 指令#

如果一个函数、模块或 API 处于 legacy 模式，这意味着它为了向后兼容性而保留，但不建议在新代码中使用，您可以使用 .. legacy:: 指令。

默认情况下，如果使用时没有参数，legacy 指令将生成以下输出

Legacy

此子模块被认为是 legacy 的，将不再收到更新。虽然我们目前没有计划删除它，但我们建议新代码改用更现代的替代方案。

我们强烈建议您也添加自定义消息，例如用于替换旧 API 的新 API。此消息将附加到默认消息

.. legacy::

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

将创建以下输出

Legacy

此子模块被认为是 legacy 的，将不再收到更新。虽然我们目前没有计划删除它，但我们建议新代码改用更现代的替代方案。新代码应使用 scipy.fft。

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

.. legacy:: function

这将创建以下输出

Legacy

此函数被认为是 legacy 的，将不再收到更新。虽然我们目前没有计划删除它，但我们建议新代码改用更现代的替代方案。

—