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