构建 NumPy API 和参考文档#
如果您只想获取文档,请注意可以在以下网址找到预构建版本:
有几种不同的格式.
开发环境#
在进一步操作之前,应该注意的是,文档是使用 make 工具构建的,该工具在 Windows 上不是原生可用的.MacOS 或 Linux 用户可以跳转到 先决条件 .建议 Windows 用户在 GitHub Codespaces (参见 推荐的开发设置 ) 或 Windows Subsystem for Linux (WSL) 上设置他们的开发环境.WSL 是持久本地设置的一个好选择.
先决条件#
构建 NumPy 文档和 API 参考需要以下内容:
NumPy#
由于主要文档的很大一部分是通过 import numpy 并检查文档字符串从 NumPy 获得的,因此您需要首先 build 并安装它,以便导入正确的版本.每次您获取存储库的最新版本时,都必须重新构建并重新安装 NumPy,然后再生成文档.这确保了 NumPy 版本和 git 存储库版本是同步的.
请注意,您可以将 NumPy 安装到临时位置,并适当地设置 PYTHONPATH 环境变量.或者,如果使用 Python 虚拟环境(通过例如 conda , virtualenv 或 venv 模块),建议将 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 ` ,请查看官方的 download 和 installation 页面,或者如果您使用的是 Linux,则可以通过您的发行版包管理器安装它.
备注
尝试安装较新版本的 ` Doxygen ` > 1.8.10,否则在构建过程中可能会收到一些警告.
子模块#
如果您通过 git 获取 NumPy,另请获取包含构建文档所需其他部分的 git 子模块:
git submodule update --init
说明#
现在您已准备好生成文档,因此请写入:
spin docs
如果您尚未这样做,这将从源代码构建 NumPy,并运行 Sphinx 以构建 html 文档.如果一切顺利,这将在 /doc 目录中生成一个 build/html 子目录,其中包含构建的文档.
以 html 和 pdf 格式分发在 https://numpy.org/doc 上的 NumPy 文档也是使用 make dist 构建的.有关如何更新 https://numpy.org/doc 的详细信息,请参阅 HOWTO RELEASE .