Creating Documentation

BLT provides macros to build documentation using Sphinx and Doxygen.

Sphinx is the documentation system used by the Python programming language project (among many others).

Doxygen is a widely used system that generates documentation from annotated source code. Doxygen is heavily used for documenting C++ software.

Sphinx and Doxygen are not built into BLT, so the sphinx-build and doxygen executables must be available via a user’s PATH at configuration time, or explicitly specified using the CMake variables SPHINX_EXECUTABLE and DOXYGEN_EXECUTABLE.

Here is an example of setting sphinx-build and doxygen paths in a host-config file:

set(SPHINX_EXECUTABLE "/usr/bin/sphinx-build" CACHE FILEPATH "")

set(DOXYGEN_EXECUTABLE "/usr/bin/doxygen" CACHE FILEPATH "")

The calc_pi example provides examples of both Sphinx and Doxygen documentation.

Calc Pi Sphinx Example

Sphinx is a python package that depends on several other packages. It can be installed via spack, pip, anaconda, etc…

sphinx-build processes a config.py file which includes a tree of reStructuredText files. The Sphinx sphinx-quickstart utility helps you generate a new sphinx project, including selecting common settings for the config.py.

BLT provides a blt_add_sphinx_target() macro which, which will look for a conf.py file in the current directory and add a command to build the Sphinx docs using this file to the docs CMake target.

blt_add_sphinx_target

A macro to create a named sphinx target for user documentation. Assumes there is a conf.py sphinx configuration file in the current directory. This macro is active when BLT is configured with a valid SPHINX_EXECUTABLE path.

Here is an example of using blt_add_sphinx_target() in a CMakeLists.txt file:

#------------------------------------------------------------------------------
# add a target to generate documentation with sphinx
#------------------------------------------------------------------------------

if(SPHINX_FOUND)
    blt_add_sphinx_target( calc_pi_sphinx )
endif()

Here is the example reStructuredText file that contains documentation for the calc_pi example.

.. Calc Pi documentation master file, created by
   sphinx-quickstart on Sun Sep 10 21:47:20 2017.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Welcome to Calc Pi's documentation!
===================================


This is a tutorial example for BLT (https://github.com/llnl/blt) that creates
C++ libraries that calculate :math:`\pi` serially and in parallel using MPI 
and CUDA.

These libraries calculate :math:`\pi` by approximating the integral 
:math:`f(x) = \int_0^14/(1+x^2)` using numerical integration.
In the MPI implementation, the intervals are distributed across MPI tasks and 
a MPI_AllReduce calculates the final result. In the CUDA implementation, the
intervals are distributed across CUDA blocks and threads and a tree reduction
calculates the final result.


The method is adapted from:
https://www.mcs.anl.gov/research/projects/mpi/usingmpi/examples-usingmpi/simplempi/cpi_c.html

Calc Pi Doxygen Example

Doxygen is a compiled executable that can be installed via spack, built-by-hand, etc…

doxygen processes a Doxyfile which specifies options, including where to look for annotated source files.

BLT provides a blt_add_doxygen_target() macro which, which will look for a Doxyfile.in file in the current directory, configure this file to create a Doxyfile in the build directory, and add a command to build the Doxygen docs using this file to the docs CMake target.

blt_add_doxygen_target

A macro to create a named doxygen target for API documentation. Assumes there is a Doxyfile.in doxygen configuration file in the current directory. This macro is active when BLT is configured with a valid DOXYGEN_EXECUTABLE path.

Here is an example of using blt_add_doxygen_target() in a CMakeLists.txt file:

#------------------------------------------------------------------------------
# add a target to generate documentation with Doxygen
#------------------------------------------------------------------------------

if(DOXYGEN_FOUND)
    blt_add_doxygen_target( calc_pi_doxygen )
endif()

Here is the example Doxyfile.in file that is configured by CMake and passed to doxygen.

#---------------------------------------
# Doxygen Config for Calc Pi Example
#---------------------------------------

PROJECT_NAME  = Calc Pi
PROJECT_BRIEF = "Calc Pi"

INPUT = @CMAKE_CURRENT_SOURCE_DIR@/../../

GENERATE_XML   = NO
GENERATE_LATEX = NO

RECURSIVE      = NO
STRIP_CODE_COMMENTS = NO

Building the Calc Pi Example Documentation

Here is an example of building both the calc_pi Sphinx and Doxygen docs using the docs CMake target:

cd build-calc-pi
make docs
...
[ 50%] Building HTML documentation with Sphinx
[ 50%] Built target calc_pi_sphinx
[ 50%] Built target sphinx_docs
[100%] Generating API documentation with Doxygen
Searching for include files...
Searching for example files...
Searching for images...
Searching for dot files...
...
lookup cache used 3/65536 hits=3 misses=3
finished...
[100%] Built target calc_pi_doxygen
[100%] Built target doxygen_docs
[100%] Built target docs

After this, you can view the Sphinx docs at:

  • build-calc-pi/docs/sphinx/html/index.html

and the Doxygen docs at:

  • build-calc-pi/docs/doxygen/html/index.html