12.10. Installing and running Sphinx (building the OpenPMIx docs) — OpenPMIx 5.0.2rc2 documentation

# 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.2. Checking Sphinx HTML links

`make linkcheck` will invoke Sphinx’s functionality to check all the external links in the documentation:

    shell$ cd docs
    shell$ make linkcheck

Important

You will need to be on a computer that has good access to the internet when running this command.

### 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