为 SciPy 文档做贡献#

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

优先级最高的是**技术上的不准确性** - docstring 缺少参数、对函数/参数/方法的错误描述，等等。其他“结构性”缺陷，如断开的链接，也优先处理。所有这些修复都很容易确认并实施。您可以 提交拉取请求 (PR) 来修复，如果您知道怎么做；否则请 打开一个问题.

**错别字和拼写错误** 处于较低的层次；我们欢迎您告诉我们这些错误，但可能无法立即修复。这些也可以通过拉取请求或问题来处理。

明显的**措辞**错误（如漏掉一个“不”）属于错别字类别，但其他措辞更改（即使是语法上的）也需要判断，这提高了标准。可以想象，在某些情况下，不清楚是否应该进行“修复”，例如

  • 尝试“修复”所有（或没有）对牛津逗号的使用。

  • 在通用用法正确性不断变化的情况下，例如“由...组成”。

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

注意

作为一般准则，尝试积累小的文档更改（如错别字），而不是逐个发送。只要有可能，还要确保使用正确的命令 跳过 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，然后重新构建来从头开始构建。

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

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

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

在云端检查文档#

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

  1. 登录 GitHub.

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

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

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

添加或编辑教程作为 Jupyter 笔记本#

在 SciPy 树的 doc/source/notebooks/ 文件夹下，您可以找到一些用 MyST-NB 格式编写的文档。这些文件是可执行的，这意味着在构建 SciPy 文档（本地或在 CI 上）时会执行它们的内容，并且执行生成的任何输出都会在最终的 HTML 文件中渲染，您可以在 用户指南 中看到这些文件。

如果您有一个用 Jupyter 笔记本格式（.ipynb 文件）编写的文档，并且想将其作为 SciPy 文档的一部分提交，有两种选择：您可以将其转换为 MyST Markdown 文件，并仅使用 .md 文件工作，或者您可以将您的 .ipynb 文件与 .md 文件配对，并同时使用这两个文件。请注意，.ipynb 文件不应提交到 SciPy 文档。

有关更多详细信息，请参阅 MyST-NB 文档。您还可以参阅 NumPy 教程上的配对教程，以获取有关 MyST-NB、Jupytext 和配对笔记本的更多信息。

如何将 .ipynb 文件转换为可执行的 .md 文件#

如果您不需要保留 .ipynb 文件，并且只想使用 MyST Markdown，请按照以下步骤操作。

  1. 使用 pip install jupytext 或 conda install jupytext -c conda-forge 安装 jupytext 工具

  2. 清除 .ipynb 文件中的所有输出

  3. 在您的终端上，运行 jupytext notebook.ipynb --to myst，其中 notebook.ipynb 应替换为要转换的文件。

现在，生成的 .md 文件（以 MyST Markdown 格式）应该包含类似于下面内容的前言，表明这是一个可执行文件

---
jupytext:
   text_representation:
      extension: .md
      format_name: myst
      format_version: 0.13
      jupytext_version: 1.14.0
kernelspec:
   display_name: Python 3 (ipykernel)
   language: python
   name: python3
---

您无需编辑此前言，因为它会自动生成。

在 Jupyter Notebook 应用程序中打开 MyST Markdown 文件#

如果您安装了 jupytext 工具，您可以在 Jupyter Notebook 应用程序中打开 MyST Markdown .md 文件并执行它们，就像您对 .ipynb 文件一样。

文档指南#

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

在指定输入参数的必要条件时，使用“必须”比“应该”更可取。对于许多英语使用者来说，“必须”意味着比“应该”更强的约束，例如“我必须有氧气才能活下去”与“我应该多锻炼”。

是

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

否

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

使用“versionadded” 标记#

  • 对于新函数，“versionadded” 标记放在“注释”部分，而不是放在 docstring 开头的描述中。

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

在“参考文献”部分中引用维基百科文章#

使用维基百科文章作为参考文献是可以接受的。创建参考文献的引用时，请包括文章标题、名称“维基百科”（类似于给出期刊名称的方式）和 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.

自包含的示例#

每个“示例”部分（在 docstring 和一般文档中）都必须是自包含的。这意味着所有导入都必须是显式的，使用的数据必须定义，并且代码在复制粘贴到新的 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 生成种子。如果未提供种子，则在执行 doctest 时使用默认值 1638083107694713882823079058616272161。无论哪种情况，渲染后的文档都不会显示种子。目的是阻止用户在代码中复制/粘贴种子，而是让他们在程序中明确地决定是否使用种子。结果是，用户无法完全复制示例的结果，因此使用随机数据的示例不应引用基于随机数据的精确数值，也不应依赖它们来阐明自己的观点。

旧版指令#

如果某个函数、模块或 API 处于 *旧版* 模式，这意味着出于向后兼容性的原因它被保留下来，但不建议在新代码中使用它，您可以使用 .. legacy:: 指令。

默认情况下，如果使用没有参数的旧版指令，它将生成以下输出

旧版

此子模块被视为旧版，不再接收更新。这也可能意味着它将在未来的 SciPy 版本中被移除。

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

.. legacy::

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

将创建以下输出

旧版

此子模块被视为旧版，不再接收更新。这也可能意味着它将在未来的 SciPy 版本中被移除。新代码应使用 scipy.fft.

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

.. legacy:: function

这将创建以下输出

旧版

此函数被视为旧版，不再接收更新。这也可能意味着它将在未来的 SciPy 版本中被移除。

—

本页内容