构建 NumPy API 和参考文档#

如果您只想获取文档,请注意,预构建版本可以在以下位置找到:

https://numpy.com.cn/doc/

以几种不同的格式。

开发环境#

在继续之前,请注意文档是使用 make 工具构建的,该工具在 Windows 上不可用。MacOS 或 Linux 用户可以直接跳到 先决条件。建议 Windows 用户在 GitHub Codespaces 上设置他们的开发环境(请参阅 推荐的开发设置)或 适用于 Linux 的 Windows 子系统 (WSL)。WSL 是持久本地设置的一个好选择。

先决条件#

构建 NumPy 文档和 API 参考需要以下内容:

NumPy#

由于主要文档的很大一部分是从 NumPy 通过 import numpy 获取并检查文档字符串,因此您需要首先 构建 并安装它,以便导入正确的版本。每次获取存储库的最新版本时,都需要重新构建和重新安装 NumPy,然后才能生成文档。这确保了 NumPy 版本和 git 存储库版本同步。

请注意,您可以例如将 NumPy 安装到临时位置并相应地设置 PYTHONPATH 环境变量。或者,如果您使用 Python 虚拟环境(例如通过 condavirtualenvvenv 模块),建议将 NumPy 安装到新的虚拟环境中。

依赖项#

构建 NumPy 文档所需的所有依赖项(除了 Doxygen)都可以使用以下命令安装:

pip install -r requirements/doc_requirements.txt

注意

可能需要安装文档依赖项的开发版本才能在本地构建文档

pip install --pre --force-reinstall --extra-index-url \
https://pypi.anaconda.org/scientific-python-nightly-wheels/simple \
-r requirements/doc_requirements.txt

我们目前使用 Sphinx 以及 Doxygen 生成 NumPy 的 API 和参考文档。此外,构建文档需要 Sphinx 扩展 plot_directive,该扩展与 Matplotlib 一起提供。我们还使用 numpydoc 在生成的 API 文档中渲染文档字符串。 SciPy 已安装,因为文档的某些部分需要 SciPy 函数。

要安装 Doxygen,请查看官方的 下载安装 页面,或者如果您使用的是 Linux,则可以通过您的发行版包管理器安装它。

注意

尝试安装较新版本的 Doxygen > 1.8.10,否则您可能会在构建过程中收到一些警告。

子模块#

如果您通过 git 获取了 NumPy,那么还需要获取包含构建文档所需的其他部分的 git 子模块

git submodule update --init

说明#

现在您已准备好生成文档,因此请编写:

spin docs

这将从源代码构建 NumPy(如果您尚未构建),并运行 Sphinx 构建 html 文档。如果一切顺利,这将在 /doc 目录中生成一个 build/html 子目录,其中包含已构建的文档。

https://numpy.com.cn/doc 上以 html 和 pdf 格式分发的 NumPy 文档也是使用 make dist 构建的。有关如何更新 https://numpy.com.cn/doc 的详细信息,请参阅 HOWTO RELEASE