Local Building of OpenMDAO Documentation

When developing new features for OpenMDAO, it will be necessary to build the documents locally, to ensure things like code embedding and formatting and links are all working the way the author intends them to work. The documentation uses jupyter notebooks, and building them requires installation of some new packages. You can install these packages by running the OpenMDAO setup script and telling it to install the documentation dependencies like this:

pip install -e .[docs]

Setup for building the MPI examples (optional)

The documentation includes several examples that demonstrate MPI features. In order to build and test their documentation, there are some additional steps. If you don’t have MPI installed, or otherwise don’t wish to build the MPI portion of the documentation, you can skip these, but you will see errors from the MPI feature docs in your build output.

The following steps only need to be done once on your local system.

jupyter serverextension enable --py ipyparallel;
ipython profile create --parallel --profile=mpi;
echo "c.IPClusterEngines.engine_launcher_class = 'MPIEngineSetLauncher'" >> ~/.ipython/profile_mpi/ipcluster_config.py;
echo "c.IPClusterStart.controller_launcher_class = 'MPIControllerLauncher'" >> ~/.ipython/profile_mpi/ipcluster_config.py;

Before you build your docs, you will need to launch a server for iPython Parallel:

ipcluster start -n 4 --profile=mpi &

This server only need to run while you build the docs, so you can terminate it afterwards.

Build all docs with build_all_docs.sh

The docs are found in the openmdao/docs directory in the OpenMDAO repo. The first time you build the docs, run:

. ./build_all_docs.sh

This will clean out any old build and build the docs completely from scratch.

Incremental build

Once you have a complete build of the docs and beging editing files, you can do an incremental build which will only rebuild the files that you touched. This can be done by running the following:

python build_jupyter_book.py

Building everything can take a while, so this is useful when making small changes to a feature.

When you create your first notebook, be sure to checkout out style guide here