How to Build the Documentation

  1. Install Python.

  2. Create and activate a virtual environment (optional, but recommended)

    python3 -m venv sphinx-env
source sphinx-env/bin/activate

    Then confirm you’re in the virtual environment:

    which python

    To leave the virtual environment:

    deactivate

  3. Install Sphinx, sphinxcontrib-matlabdomain, sphinx-tabs and sphinx-rtd-theme

    pip install -U sphinx
pip install -U sphinxcontrib-matlabdomain
pip install -U sphinx-tabs
pip install -U sphinx-rtd-theme

  4. Install TeXLive (for building LaTeX/PDF output).

  5. In the docs/sphinx directory, type:

    make html
make latexpdf

    … twice. That’s right, you re-run make html after the LaTeX build so it can pick up the links to the PDF and then re-run make latexpdf to ensure that tables of contents, cross-references, etc. are all up to date.

    If everything builds properly, you should find the PDF manuals in docs/sphinx/build/latex and the HTML documentation in docs/sphinx/build/html (start with index.html).

Updating the Reference Manual

The source files for the MATPOWER Reference Manual require the creation of .rst stub files for many classes and functions. To avoid having Sphinx parse and analyze functions and classes that are not included in the manual, we symlink only those explicitly included into a source subdirectory.

The generate_matpower_autodoc() function is used to automatically generate these stub files and symlinks from explicit, hard-coded lists of classes and functions.

The following steps should be followed when a new class or function are added to MATPOWER.

  1. Add the name of the function or class to the appropriate cell array in lib/t/generate_matpower_autodoc.m.

2. Re-run generate_matpower_autodoc() from the MATLAB prompt.

generate_matpower_autodoc(<path-to-MATPOWER>)

  1. Rebuild the MATPOWER documention as in Step 5 above.

If functions or classes are removed from MATPOWER they should be removed from the lists in lib/t/generate_matpower_autodoc.m and the stub files deleted from docs/sphinx/source/ref-manual and symlinks deleted from docs/sphinx/source/matlab-source.

Reference Manual Utility Functions