How to Build the Documentation
Install Python.
Create and activate a virtual environment (optional, but recommended)
python3 -m venv sphinx-env source sphinx-env/bin/activate
python3 -m venv sphinx-env .\sphinx-env\Scripts\activate
Then confirm you’re in the virtual environment:
which python
where python
To leave the virtual environment:
deactivate
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
Install TeXLive (for building LaTeX/PDF output).
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-runmake 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 indocs/sphinx/build/html
(start withindex.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.
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>)
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
.