12.10. Installing and running Sphinx (building the OpenPMIx docs)

As with all content in the Developer’s Guide, this section is only relevant for developers who work in the OpenPMIx code base itself. End users who install a binary OpenPMIx package or build from an official OpenPMIx distribution tarball do not need to have Sphinx installed.

12.10.1. Installing Python

The Sphinx tool is written in Python, and therefore needs to have Python available. As of late 2022, Sphinx requires Python >= v3.7.

This documentation does not contain detailed instructions for installing a Python version sufficient for using Sphinx. Consult your local OS documentation for how to obtain Python >= v3.7, or search the internet for further information.

12.10.2. 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.2.1. Install Sphinx in a Python virtual environment

The preferred method of installing Sphinx for OpenPMIx 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 OpenPMIx Git clone directory:

# Create the Python virtual environment
shell$ cd TOP_OF_OpenPMIx_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.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_OpenPMIx_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 OpenPMIx 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.2.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_OpenPMIx_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 OpenPMIx 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.

12.10.3. Running Sphinx

OpenPMIx’s build environment is setup to invoke Sphinx automatically; you should not need to invoke Sphinx manually.

Important

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

As long as configure found Sphinx, make will invoke Sphinx to build the documentation. You can also run make directly in the docs/ directory to build just the docs and skip building the rest of the OpenPMIx software. This can be a huge time-saver when iteratively writing, rendering, and viewing/proofing documentation.

Note

The fully-built HTML and man page docs are included in official OpenPMIx distribution tarballs. Meaning: if you download an official distribution OpenPMIx tarball, the pre-built HTML and man page files are included in the tarball.

Sphinx is a requirement for developers who want to build the OpenPMIx docs. End users do not need to have Sphinx available to build OpenPMIx or have its docs installed from an official distribution tarball.

12.10.3.1. Sphinx execution time

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

Caution

Sphinx is only somewhat smart in its partial re-rendering. If you change a title in an RST file, for example, Sphinx will (by default) only re-render that page. The Tables of Contents / left hand navigation on other pages may not be updated.

You can always force a full re-render via:

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

12.10.3.3. Viewing docs locally

Once you have built the docs in your local Git clone, you can view them locally in the build tree:

  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. Use the man command to view the Nroff files in docs/_build/man (you may need to use an absolute or relative filename to prevent man from using its search paths). For example:

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

Alternatively, you can view these files in their installed locations after running make install:

  1. The HTML docs are installed (by default) to $prefix/share/doc/pmix/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/pmix/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 PMIx_Abort