LBANN Documentation Building

Warning

Some of the directions in this section are Mac-specific.

Adding Documentation Outside Code

  1. Create a file such as “new_docs.rst” in “lbann/docs”.

  2. Add “new_docs” (no “.rst”) to the appropriate documentation block in “lbann/docs/index.rst”.

  3. Look at the other “.rst” files in “lbann/docs” to see how to get certain formatting.

  4. When you want to see how your code looks, you have a couple options:

    1. 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.

    2. From “lbann/docs” run make html and then open -a <preferred web browser> _build/html/index.html. This is exactly how the docs will look.

  5. 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:

  1. Run pip3 install sphinx breathe sphinx-rtd-theme.

  2. Download Doxygen by going to the Doxygen downloads page, downloading “Doxygen-1.8.15.dmg”, and dragging the app to the “Applications” folder.

  3. 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”.

  4. Add Doxygen to your path with PATH="<doxygen directory>:${PATH}". You may want to add this to your “~/.bash_profile” so your PATH is always correct. Run source ~/.bash_profile to run that code.

  5. Try running make html again.