Ctrl+K

为 SciPy 文档贡献力量#

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

优先级最高的是 **技术上的不准确性** - 文档字符串缺少参数、函数/参数/方法的描述错误等等。其他“结构性”缺陷，例如断开的链接，也优先考虑。所有这些修复都易于确认和实施。如果您知道如何操作，可以 提交一个拉取请求 (PR) 来进行修复；否则，请 打开一个问题。

**错别字和拼写错误** 优先级较低；我们欢迎您告知这些错误，但可能无法及时修复。这些也可以通过拉取请求或问题来处理。

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

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

  • 一些常见用法正确性正在演变的案例，例如“comprised of”。

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

注意

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

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

使用 Sphinx 在本地渲染文档#

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

有关视频演练，请参阅 使用 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”标记位于“Notes”部分，而不是 docstring 开头的描述中。

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

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

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

—

本页内容