LBANN Documentation Building
Warning
Some of the directions in this section are Mac-specific.
Adding Documentation Outside Code
Create a file such as “new_docs.rst” in “lbann/docs”.
Add “new_docs” (no “.rst”) to the appropriate documentation block in “lbann/docs/index.rst”.
Look at the other “.rst” files in “lbann/docs” to see how to get certain formatting.
When you want to see how your code looks, you have a couple options:
Push your docs to your fork/branch on GitHub and look at how the text renders. This is a very simplified look compared to Read-the-Docs.
From “lbann/docs” run
make html
and thenopen -a <preferred web browser> _build/html/index.html
. This is exactly how the docs will look.
Merge your code into “lbann/develop” and then have someone with correct permissions on Read-the-Docs update the official docs.
Making The Build Work
In order to make make html
work, you may need to do a few steps:
Run
pip3 install sphinx breathe sphinx-rtd-theme
.Download Doxygen by going to the Doxygen downloads page, downloading “Doxygen-1.8.15.dmg”, and dragging the app to the “Applications” folder.
Determine the directory Doxygen is in by running which Doxygen. If nothing is returned, see if doxygen is in “/Applications/Doxygen.app/Contents/Resources” or “/Applications/Doxygen.app/Contents/MacOS”.
Add Doxygen to your path with
PATH="<doxygen directory>:${PATH}"
. You may want to add this to your “~/.bash_profile” so yourPATH
is always correct. Runsource ~/.bash_profile
to run that code.Try running
make html
again.