Documenting projects using brainvisa-cmake

Documentation in software projects is supported via external tools like Doxygen or Sphinx, and are integrated in brainvisa-cmake infrastructure.

Documentation is generated within the doc step of bv_maker:

bv_maker doc

Alternatively, building documentation can be triggered via the make command from a build directory. Several targets control documentation:

make doc

will build all docs

make usrdoc

will build user documentations

make devdoc

will build development documentations

and generally project-specific targets will exist, like for instance:

make brainvisa-cmake-usrsphinx
make anatomist-free-devdoc

etc.

Documentation for a project will be generated in a subdirectory of the build tree, in:

share/doc/<project>-<version>

Doxygen documentation

Doxygen is used to genrate API documentation for C++ sources. It generates HTML pages, an possibly other formats, which we are not using in brainvisa-cmake.

In brainvisa-cmake projects, such documentation should be setup in the CMake config files of the project. Typically we set it in the main CMakeLists.txt file at the root of the project.

Doxygen docs will be part of the development documentations.

• The Doxygen component has to be found using find_package( Doxygen )

• Brainvisa-cmake provides a function brainvisa_generate_doxygen_doc to build Doxygen doc:

Exaple, from the Cartobase project:

find_package( Doxygen )
if( DOXYGEN_FOUND )
  set( DOXYFILE_PREDEFINED "${SOMA-IO_DEFINITIONS}")
  set( _doxyheaders ${_headers} "config/config.h" ) # add config.h file
  BRAINVISA_GENERATE_DOXYGEN_DOC(
    _doxyheaders
    INPUT_PREFIX "${CMAKE_BINARY_DIR}/include/cartobase"
    COMPONENT "cartobase" )
endif()

A more complete example, from Anatomist:

find_package( Doxygen )
if( DOXYGEN_FOUND )
  set( DOXYFILE_HTML_HEADER "\"${CMAKE_CURRENT_SOURCE_DIR}/head_anatomist.html\"" )
  set( _doxygenInput ${HEADERS} )
  set( DOXYFILE_PREDEFINED ${ANATOMIST_DEFINITIONS} ${AIMS-FREE_DEFINITIONS}
    ${SOMA-IO_DEFINITIONS} CARTO_USE_BLITZ )
  set(aims-free_version
    "${aims-free_VERSION_MAJOR}.${aims-free_VERSION_MINOR}")
  set(_somaio_version "${soma-io_VERSION_MAJOR}.${soma-io_VERSION_MINOR}")
  set( DOXYFILE_TAGFILES
    "${CMAKE_BINARY_DIR}/share/doc/aimsgui-${aims-free_version}/doxygen/aimsgui.tag=../../aimsgui-${aims-free_version}/doxygen ${CMAKE_BINARY_DIR}/share/doc/aimsdata-${aims-free_version}/doxygen/aimsdata.tag=../../aimsdata-${aims-free_version}/doxygen ${CMAKE_BINARY_DIR}/share/doc/graph-${aims-free_version}/doxygen/graph.tag=../../graph-${aims-free_version}/doxygen ${CMAKE_BINARY_DIR}/share/doc/cartobase-${_somaio_version}/doxygen/cartobase.tag=../../cartobase-${_somaio_version}/doxygen ${CMAKE_BINARY_DIR}/share/doc/soma-io-${_somaio_version}/doxygen/soma-io.tag=../../cartobase-${_somaio_version}/doxygen ${CMAKE_BINARY_DIR}/share/doc/cartodata-${aims-free_version}/doxygen/cartodata.tag=../../cartodata-${aims-free_version}/doxygen")
  BRAINVISA_GENERATE_DOXYGEN_DOC(
    _doxygenInput
    head_anatomist.html anatomist.png anatomist.gif
    INPUT_PREFIX "${CMAKE_BINARY_DIR}/include/anatomist"
    COMPONENT "anatomist" )
  add_dependencies( anatomist-doxygen aimsgui-doxygen aimsdata-doxygen graph-doxygen soma-io-doxygen cartobase-doxygen cartodata-doxygen )
endif()

Sphinx documentation

Sphinx is used to build HTML documentation pages. It can be used to make general documentation, and can also make API documentation for Python classes and modules.

In CMake configuration

brainvisa-cmake provides a function to build sphinx documentation for a project: brainvisa_generate_sphinx_doc.

find_package( Sphinx )
BRAINVISA_GENERATE_SPHINX_DOC( "sphinxdoc/user_doc"
  "share/doc/axon-${BRAINVISA_PACKAGE_VERSION_MAJOR}.${BRAINVISA_PACKAGE_VERSION_MINOR}/user_doc" USER )
BRAINVISA_GENERATE_SPHINX_DOC( "sphinxdoc/dev_doc"
  "share/doc/axon-${BRAINVISA_PACKAGE_VERSION_MAJOR}.${BRAINVISA_PACKAGE_VERSION_MINOR}/dev_doc" )

In pure python projects

In pure python projects, the CMake configuration file is not present in the sources, and is generated by bv_maker. If the project sources contain a directory tree doc/sources, then bv_maker will consider it as a Sphinx source directory and configure it to generate sphinx development docs, as in the CMake case.

Sphinx sources

Sphinx sources should be located in a subdirectory of the project sources tree. The directory should contain the conf.py file expected by sphinx.

For new developers, in a few words, Sphinx sources are text files using a markup language, ReStructuredText which is fairly simple and mostly human readable.

The entry point is generally a index.rst file which may include other ones.

Customization

Using CMake commands, it is possible to mix Doxygen or Sphinx docs with other processings, for instance generation of commandline help, or pre-building of HTML tables etc. All kinds of scripts can be triggered by CMake when generating docs, and the Sphinx builds, especially, may use a part of sources which could be generated by other scripts.

In BrainVisa, we use it for instance to build the complete web site http://brainvisa.info