构建 NumPy API 和参考文档#

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

https://numpy.org/doc/

以几种不同的格式.

开发环境#

在继续之前需要注意的是,文档是使用 make 工具构建的,这在 Windows 上不是原生可用的.MacOS 或 Linux 用户可以跳转到 前提条件.建议 Windows 用户在 GitHub Codespaces 上设置他们的开发环境（参见 推荐的开发设置）或使用 Windows Subsystem for Linux (WSL).WSL 是持久本地设置的一个好选项.

前提条件#

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

NumPy#

由于主文档的大部分内容是通过 import numpy 并检查文档字符串从 NumPy 获取的,因此您需要首先 构建 并安装它,以便导入正确版本的 NumPy.每次获取仓库的最新版本后,在生成文档之前,必须重新构建并重新安装 NumPy.这确保了 NumPy 版本和 git 仓库版本同步.

请注意,例如,您可以将 NumPy 安装到临时位置,并适当地设置 PYTHONPATH 环境变量.或者,如果使用 Python 虚拟环境（通过例如 conda、virtualenv 或 venv 模块）,建议将 NumPy 安装到新的虚拟环境中.

依赖项#

除了 Doxygen 之外,构建 NumPy 文档所需的所有必要依赖项都可以通过以下方式安装:

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.org/doc 上分发的 NumPy 文档以 html 和 pdf 格式构建,也可以通过 make dist 构建.有关如何更新 https://numpy.org/doc 的详细信息,请参阅 HOWTO RELEASE.

On this page