12.10. Installing Sphinx

The Sphinx documentation recommends installing Sphinx (and its required Python dependencies) via pip, which typically requires connectivity to the general internet.

Note

If you are running on MacOS, you may be tempted to use Homebrew or MacPorts to install Sphinx. The Sphinx documentation recommends against this. Instead, you should use pip to install Sphinx.

There are three general ways to install Sphinx; you only need one of them.

12.10.1. Install Sphinx in a Python virtual environment

The preferred method of installing Sphinx for Open MPI documentation development is to install Sphinx in a Python virtual environment. This places Sphinx in a sandbox that will not conflict with other pip-installed Python modules. This example installs Sphinx and other Python modules in the ompi-docs-venv tree under your Open MPI Git clone directory:

# 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

Note that sourcing the activate script will change your prompt to put the name of your virtual environment directory at the front, just as a visual reminder that you are operating in a Python virtual environment. You can run deactivate to leave the virtual environment.

Important

You will need to source the activate script to put Sphinx in your PATH before running configure.

12.10.2. Install Sphinx globally

If Python virtual environments are not desirable on your system, you can install Sphinx globally on your system (you may need to run with root privileges):

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

This will install Sphinx and some Python modules required for building the Open MPI documentation in a system-wide location.

This will likely install the sphinx-build executable in a location that is already in your PATH. If the location is not already in your PATH, then you need to add it to your PATH.

Important

You will need to ensure that Sphinx is in your PATH before running configure.

12.10.3. Install Sphinx locally

If you cannot or do not want to install Sphinx globally on your system, the following will install Sphinx somewhere under your $HOME. It is the same pip command as shown above, but with the addition of the --user flag (you should not need root permissions to run this command):

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

This will install Sphinx and some Python modules required for building the Open MPI documentation in a system-wide location.

You will likely need to find the location where sphinx-build was installed and add it to your PATH.

Note

On MacOS, look for sphinx-build under $HOME/Library/Python/VERSION/bin (where VERSION is the version number of Python). Or it may have installed to /usr/local/bin/sphinx-build. YMMV.

Important

You will need to ensure that Sphinx is in your PATH before running configure.