为 SciPy 文档做贡献#

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

首要任务是解决 技术性错误 —— 例如缺少参数的文档字符串、函数/参数/方法的错误描述等。其他“结构性”缺陷,如损坏的链接,也优先处理。所有这些修复都很容易确认并实施。如果你知道如何操作,可以 提交一个拉取请求 (PR);否则请 打开一个问题

拼写错误 处于较低的优先级;我们欢迎听到关于这些问题的反馈,但可能无法及时修复。这些问题也可以通过拉取请求或问题来处理。

明显的 措辞 错误(如遗漏“not”)属于拼写错误类别,但其他改写——即使是语法上的——需要判断,这提高了门槛。可以想象一些情况,不清楚是否应该进行“修复”,例如:

  • 尝试“修复”所有使用(或未使用)牛津逗号的情况。

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

最容易接受的修复是那些原始版本明显且明确错误的地方;需要微妙编辑判断的更改可能最好避免。(但请注意,这并不涉及更新文档以修正令人困惑的陈述或处理用户报告的文档问题。)

备注

作为一般指导原则,尽量积累小的文档更改(如拼写错误),而不是逐一发送。如果可能,还要确保使用正确的命令来 跳过CI检查 在文档更改上。

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

使用 Sphinx 在本地渲染文档#

SciPy 文档字符串使用 SphinxPyData Sphinx 主题 渲染为 HTML。编写文档字符串的内容在 Documentation style 中有所涉及;本文档解释了如何检查文档字符串是否正确渲染。

如需视频演示,请参见 使用Sphinx渲染SciPy文档

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

  1. 确保你有一个可用的 SciPy 构建(参见 从源代码构建)。

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

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

备注

  • 对某些文档的更改在重新构建 Sphinx 文档时不会生效。在这种情况下,您可以通过删除目录 scipy/doc/buildsource/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. 在“Check the rendered docs here!”旁边,选择“Details”。

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

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

如果你有一个用 Jupyter 笔记本格式(一个 .ipynb 文件)编写的文档,并且希望将其作为 SciPy 文档的一部分提交,有两种选择:你可以将其转换为 MyST Markdown 文件,只使用 .md 文件,或者你可以将你的 .ipynb 文件与一个 .md 文件配对,并同时使用两者。请注意,.ipynb 文件 不应该 提交到 SciPy 文档中。

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

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

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

  1. 使用 pip install jupytextconda 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’ 标记应放在“注释”部分,而不是放在文档字符串开头的描述中。

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

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

使用维基百科文章作为参考是可以接受的。在创建参考文献时,包括文章标题、名称“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.

自包含示例#

每个“示例”部分(无论是在文档字符串中还是一般文档中)都必须是自包含的。这意味着所有导入必须是显式的,使用的数据必须定义,代码在复制粘贴到新的 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:: 指令。

默认情况下,如果没有任何参数使用,旧版指令将生成以下输出:

传统

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

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

.. legacy::

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

将创建以下输出:

传统

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

最后,如果你想提及一个函数、方法(或任何自定义对象)而不是一个 子模块 ,你可以使用一个可选参数:

.. legacy:: function

这将创建以下输出:

传统

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