==========================================
Documenting projects using brainvisa-cmake
==========================================

Documentation in software projects is supported via external tools like `Doxygen <http://www.doxygen.org>`_ or `Sphinx <http://sphinx-doc.org>`_, and are integrated in brainvisa-cmake infrastructure.

Documentation is generated within the ``doc`` step of ``bv_maker``:

.. code-block:: bash

    bv_maker doc

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

.. code-block:: bash

    make doc

will build all docs

.. code-block:: bash

    make usrdoc

will build user documentations

.. code-block:: bash

    make devdoc

will build development documentations

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

.. code-block:: bash

    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 <http://www.doxygen.org>`_ 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 :ref:`brainvisa_generate_doxygen_doc` to build Doxygen doc:

Exaple, from the Cartobase project:

.. code-block:: cmake

    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:

.. code-block:: cmake

    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 <http://sphinx-doc.org>`_ 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: :ref:`brainvisa_generate_sphinx_doc`.

.. code-block:: cmake

    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 <http://docutils.sourceforge.net/rst.html>`_ 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