13.10. 安装与运行Sphinx（构建Open MPI文档）

与开发者指南中的所有内容一样，本节仅适用于在Open MPI代码库中工作的开发人员。通过二进制Open MPI安装包或官方Open MPI发行版tarball构建的最终用户无需安装Sphinx。

13.10.1. 安装Python

Sphinx工具是用Python编写的，因此需要安装Python环境。截至2022年底，Sphinx要求Python版本≥v3.7。

本文档不包含关于安装适用于使用Sphinx的Python版本的详细说明。如需获取Python >= v3.7，请查阅您本地操作系统的文档，或在互联网上搜索更多信息。

13.10.2. 安装Sphinx

The Sphinx documentation 推荐通过pip安装Sphinx(及其所需的Python依赖项)，这通常需要连接到公共互联网。

注意

如果您在MacOS系统上运行，可能会考虑使用Homebrew或MacPorts来安装Sphinx。但Sphinx官方文档不建议采用这种方式。相反，您应该使用pip来安装Sphinx。

安装Sphinx通常有三种方法；您只需选择其中一种即可。

13.10.2.1. 在Python虚拟环境中安装Sphinx

为Open MPI文档开发安装Sphinx的首选方法是在Python虚拟环境中安装Sphinx。这种方式将Sphinx置于一个沙箱环境中，不会与其他通过pip安装的Python模块产生冲突。以下示例将在您Open MPI Git克隆目录下的ompi-docs-venv目录树中安装Sphinx及其他Python模块：

# Create the Python virtual environment
shell$ cd TOP_OF_OPEN_MPI_GIT_CLONE
shell$ python3 -m venv ompi-docs-venv
# Or: python3 -m virtualenv ompi-docs-venv
# Or: virtualenv --python=python3 ompi-docs-venv

# Activate the virtual environment
shell$ . ./ompi-docs-venv/bin/activate

# Notice that the shell prompt changes
# Now install the required Python modules
(ompi-docs-venv) shell$ pip3 install -r docs/requirements.txt
# Or: python3 -m pip install install -r docs/requirements.txt

请注意，执行activate脚本会修改您的命令行提示符，将虚拟环境目录名称显示在最前面，这是为了直观提醒您当前正在Python虚拟环境中操作。您可以运行deactivate命令来退出虚拟环境。

重要

在运行configure之前，你需要先执行activate脚本将Sphinx添加到你的PATH环境变量中。

13.10.2.2. 全局安装Sphinx

如果您的系统不适合使用Python虚拟环境，您可以在系统全局安装Sphinx（可能需要使用root权限运行）：

shell$ cd TOP_OF_OPEN_MPI_GIT_CLONE
shell$ pip3 install -r docs/requirements.txt
# Or: python3 -m pip install install -r docs/requirements.txt

这将在系统范围内安装Sphinx和一些构建Open MPI文档所需的Python模块。

这很可能会将sphinx-build可执行文件安装到您PATH环境变量已包含的路径中。如果该路径尚未包含在您的PATH中，则需要将其添加到PATH环境变量里。

重要

在运行configure之前，您需要确保Sphinx已添加到PATH环境变量中。

13.10.2.3. 本地安装Sphinx

如果您无法或不想在系统上全局安装Sphinx，以下命令将在您的$HOME目录下安装Sphinx。这与上面显示的pip命令相同，但添加了--user标志（运行此命令应该不需要root权限）：

shell$ cd TOP_OF_OPEN_MPI_GIT_CLONE
shell$ pip3 install --user -r docs/requirements.txt
# Or: python3 -m pip install install -r docs/requirements.txt

这将在用户特定位置安装Sphinx和一些构建Open MPI文档所需的Python模块，通常位于$HOME目录下的某个位置

您可能需要找到sphinx-build的安装位置并将其添加到PATH环境变量中（例如，在macOS系统上，它可能位于$HOME/Library/Python/PYTHON_VERSION/bin/sphinx-build路径下）。

注意

在MacOS系统上，请在$HOME/Library/Python/VERSION/bin目录下查找sphinx-build（其中VERSION是Python的版本号）。或者它可能被安装到了/usr/local/bin/sphinx-build路径下。具体情况可能有所不同。

重要

在运行configure之前，您需要确保Sphinx已包含在您的PATH环境变量中。

13.10.3. 运行Sphinx

Open MPI的构建环境已设置为自动调用Sphinx；您通常无需手动调用Sphinx。

重要

在运行configure之前，您需要确保Sphinx已包含在PATH环境变量中。

只要configure检测到Sphinx，make就会调用Sphinx来构建文档。您也可以直接在docs/目录下运行make来仅构建文档而跳过Open MPI软件的其余部分构建。这在迭代式编写、渲染和查看/校对文档时能大幅节省时间。

注意

The fully-built HTML and man page docs are included in official Open MPI distribution tarballs. Meaning: if you download an Open MPI tarball from https://www.open-mpi.org/software/ompi (version v5.0.0 or later), the pre-built HTML and man page files are included in the tarball.

Sphinx是希望构建Open MPI文档的开发者所需的工具。终端用户无需安装Sphinx即可构建Open MPI或从其官方发布包中安装文档。

13.10.3.1. Sphinx执行时间

首次在干净的代码库上调用Sphinx时，渲染所有文档会花费一些时间。

However, Sphinx is stateful: subsequent runs can be significantly faster because Sphinx will only re-render HTML files that have changes. This is an enormous time saver for Open MPI (e.g., if you are iterating over writing the docs and running make to see how they rendered in HTML).

警告

Sphinx在部分重新渲染方面只是稍微智能一些。例如，如果您在RST文件中更改标题，Sphinx（默认情况下）只会重新渲染该页面。其他页面上的目录/左侧导航可能不会更新。

您随时可以通过以下方式强制进行完整重新渲染：

shell$ cd docs
shell$ rm -rf _build
shell$ make

13.10.3.3. 本地查看文档

在本地Git克隆中构建文档后，您可以在构建树中本地查看它们：

  1. Open docs/_build/html/index.html in a browser to view the HTML docs. For example, on MacOS, the following command opens the build tree docs in the default web browser:

    shell$ open docs/_build/html/index.html

  2. 使用man命令查看docs/_build/man目录下的Nroff文件（可能需要使用绝对或相对路径来防止man命令使用其默认搜索路径）。例如：

    shell$ cd docs/_build/man
shell$ man ./MPI_Send.3

或者，您也可以在运行make install后查看这些文件在安装位置中的内容：

  1. The HTML docs are installed (by default) to $prefix/share/doc/openmpi/html. You can use a web browser to open the index.html in that directory to view the docs locally. For example, on MacOS, the following command opens the installed docs in the default web browser:

    shell$ open $prefix/share/doc/openmpi/html/index.html

  2. The man pages are installed (by default) to $preix/share/man. If your man page search path includes this location, you can invoke commands similar to the following to see the same content that you see in these HTML pages:

    shell$ man MPI_Send