Initial implementation of the sphinx-based CMake API documentation

This includes the following workflow:

* The cmake module path is globbed for any modules matching *.cmake
* The opening comment is parsed for the following rst directives:
  cmake_function, cmake_module, cmake_variables
* From those, a browsable documentation is generated.

To run properly, a python interpreter and sphinx are needed.

.gitignore

@@ -5,6 +5,7 @@
 *.o
 *.trs
 *~
+*.pyc
 .deps/
 .libs/
 Makefile

cmake/modules/AddGMPFlags.cmake

-# add_dune_gmp_flags(target1 target2 ...)
-# Function that adds GMP flags to the specified targets
+# Defines the functions to use GMP
 #
+# .. cmake_function:: add_dune_gmp_flags
+#
+#    .. cmake_param:: targets
+#       :positional:
+#       :single:
+#       :required:
+#
+#       A list of targets to use GMP with.
+#
+
+
 function(add_dune_gmp_flags _targets)
   if(GMP_FOUND)
     foreach(_target ${_targets})

cmake/modules/AddMETISFlags.cmake

-# Module providing convenience functions for using METIS
+# Defines the functions to use METIS
 #
-# Provides the following functions:
+# .. cmake_function:: add_dune_metis_flags
 #
-# add_dune_metis_flags(target1 target2 ...)
+#    .. cmake_param:: targets
+#       :positional:
+#       :single:
+#       :required:
 #
-# Adds the necessary flags to compile and link the targets with ParMETIS support.
+#       A list of targets to use METIS with.
 #
+
+
 function(add_dune_metis_flags _targets)
   if(METIS_FOUND)
     foreach(_target ${_targets})

cmake/modules/AddPTScotchFlags.cmake

-# Module providing convenience functions for using PT-Scotch
+# Defines the functions to use PTScotch
 #
-# Provides the following functions:
+# .. cmake_function:: add_dune_ptscotch_flags
 #
-# add_dune_ptscotch_flags(target1 target2 ...)
+#    .. cmake_param:: targets
+#       :positional:
+#       :single:
+#       :required:
 #
-# Adds the necessary flags to compile and link the targets with PT-Scotch support.
+#       A list of targets to use PTScotch with.
 #
+
+
 function(add_dune_ptscotch_flags _targets)
   if(PTSCOTCH_FOUND)
     foreach(_target ${_targets})

cmake/modules/AddParMETISFlags.cmake

-# Module providing convenience functions for using ParMETIS
+# Defines the functions to use ParMETIS
 #
-# Provides the following functions:
+# .. cmake_function:: add_dune_parmetis_flags
 #
-# add_dune_parmetis_flags(target1 target2 ...)
+#    .. cmake_param:: targets
+#       :positional:
+#       :single:
+#       :required:
 #
-# Adds the necessary flags to compile and link the targets with ParMETIS support.
+#       A list of targets to use ParMETIS with.
 #
+
+
 function(add_dune_parmetis_flags _targets)
   if(PARMETIS_FOUND)
     foreach(_target ${_targets})

cmake/modules/AddUMFPackFlags.cmake

-# module providing convenience mehtods for compiling bianries with UMFPack support
+# Defines the functions to use UMFPack
 #
-# Provides the following functions:
+# .. cmake_function:: add_dune_umfpack_flags
 #
-# add_dune_umfpack_flags(target1 target2...)
+#    .. cmake_param:: targets
+#       :positional:
+#       :single:
+#       :required:
 #
-# adds UMFPack flags to the targets for compilation and linking
+#       A list of targets to use UMFPack with.
+#
+
+
 function(add_dune_umfpack_flags _targets)
   if(UMFPACK_FOUND)
     foreach(_target ${_targets})
@@ -15,4 +21,4 @@ function(add_dune_umfpack_flags _targets)
         "${_props} ${UMFPACK_DUNE_COMPILE_FLAGS} -DENABLE_UMFPACK")
     endforeach(_target ${_targets})
   endif(UMFPACK_FOUND)
-endfunction(add_dune_umfpack_flags)
\ No newline at end of file
+endfunction(add_dune_umfpack_flags)

cmake/modules/CMakeLists.txt

@@ -15,6 +15,7 @@ set(modules
   DuneMacros.cmake
   DuneMPI.cmake
   DunePkgConfig.cmake
+  DuneSphinxCMakeDoc.cmake
   DuneStreams.cmake
   DuneSymlinkOrCopy.cmake
   DuneTestMacros.cmake
@@ -26,6 +27,7 @@ set(modules
   FindMProtect.cmake
   FindParMETIS.cmake
   FindPTScotch.cmake
+  FindSphinx.cmake
   FindThreadsCMake31.cmake
   FindUMFPack.cmake
   Headercheck.cmake

cmake/modules/CheckCXXFeatures.cmake

+# .. cmake_module::
 #
-# Module that checks for supported C++14, C++11 and non-standard features.
+#    Module that checks for supported C++14, C++11 and non-standard features.
 #
-# Sets the follwing variables:
+#    The behaviour of this module can be modified by the following variable:
 #
-# HAVE_NULLPTR                     True if nullptr is available
-# HAS_ATTRIBUTE_UNUSED             True if attribute unused is supported
-# HAS_ATTRIBUTE_DEPRECATED         True if attribute deprecated is supported
-# HAS_ATTRIBUTE_DEPRECATED_MSG     True if attribute deprecated("msg") is supported
-# HAVE_CONSTEXPR                   True if constexpr is supported
-# HAVE_KEYWORD_FINAL               True if final is supported.
-# HAVE_RANGE_BASED_FOR             True if range-based for is supported and working.
-# HAVE_NOEXCEPT_SPECIFIER          True if nonexcept specifier is supported.
+#    :ref:`DISABLE_CXX_VERSION_CHECK`
+#       Disable checking for std=c++11 (c++14, c++1y)
 #
-# Input variables:
+#    This module internally sets the following variables, which are then
+#    exported into the config.h of the current dune module.
 #
-# DISABLE_CXX_VERSION_CHECK        Disable checking for std=c++11 (c++14, c++1y)
+#    :code:`HAVE_NULLPTR`
+#       True if nullptr is available
+#
+#    :code:`HAS_ATTRIBUTE_UNUSED`
+#       True if attribute unused is supported
+#
+#    :code:`HAS_ATTRIBUTE_DEPRECATED`
+#       True if attribute deprecated is supported
+#
+#    :code:`HAS_ATTRIBUTE_DEPRECATED_MSG`
+#       True if attribute deprecated("msg") is supported
+#
+#    :code:`HAVE_CONSTEXPR1`
+#       True if constexpr is supported
+#
+#    :code:`HAVE_KEYWORD_FINAL`
+#       True if final is supported.
+#
+#    :code:`HAVE_RANGE_BASED_FOR`
+#       True if range-based for is supported and working.
+#
+#    :code:`HAVE_NOEXCEPT_SPECIFIER`
+#       True if nonexcept specifier is supported.
+#
+# .. cmake_variable:: DISABLE_CXX_VERSION_CHECK
+#
+#    You may set this variable to TRUE to disable checking for
+#    std=c++11 (c++14, c++1y). For more details, check :ref:`CheckCXXFeatures`.
+#
+
 
 include(CMakePushCheckState)
 cmake_push_check_state()

cmake/modules/DuneCMakePackageConfigHelpers.cmake

+# .. cmake_module::
+#
+#    .. note::
+#       This module should be removed soon, as it provides fallbacks for pre 2.8.8
 #
 # A poor mans version of CMakePackageConfigHelpers.cmake for as a substitute
 # for old Cmake versions.

cmake/modules/DuneCommonMacros.cmake

-# This cmake file holds tests and directives that are executed
-# for the module dune-common and have to be executed by
-# all dependent modules
+# .. cmake_module::
 #
-# Specifically it configure the DUNE debug streams and
-# tests whether LAPACK and BLAS are available.
+#    This modules content is executed whenever a module required or suggests dune-common!
 #
+
 include(DuneStreams)
 dune_set_minimal_debug_level()
 

cmake/modules/DuneCxaDemangle.cmake

-# Module that checks whether the compiler supports the
+# This Module checks whether the compiler supports the
 # abi::__cxa_demangle function required to
 # make the type names returned by typeid() human-readable
 #
-# Sets the following variable:
-# HAVE_CXA_DEMANGLE
+# It sets the a variable :code:`HAVE_CXA_DEMANGLE` with the result.
 #
-# perform tests
+
 include(CheckCXXSourceCompiles)
 
 CHECK_CXX_SOURCE_COMPILES("#include <typeinfo>

cmake/modules/DuneDoc.cmake

@@ -15,7 +15,30 @@
 # If DEPENDENCY is specified, this is a dependency for
 # the installation. Otherwise FILENAME becomes the dependency
 #
-# dune_add_latex_document()
+# .. cmake_function:: dune_add_latex_document
+#
+#    .. cmake_brief::
+#
+#       build a pdf document through the dune buildsystem.
+#
+#    .. cmake_param:: texfile
+#       :single:
+#       :required:
+#       :positional:
+#
+#       The texfile to compile into a pdf.
+#
+#    .. note::
+#
+#       This function will be rewritten for Dune 3.0 as it currently
+#       shadows all options provided by the base implementation
+#       :code:`add_latex_document`.
+#
+# .. cmake_function:: create_doc_install
+#
+#    .. todo::
+#
+#       Evaluate use cases for this function.
 
 FIND_PACKAGE(LATEX)
 FIND_PROGRAM(IMAGEMAGICK_CONVERT convert
@@ -47,6 +70,9 @@ endif(LATEX_USABLE)
 
 add_custom_target(doc)
 
+# add the Sphinx-generated build system documentation
+include(DuneSphinxCMakeDoc)
+
 
 MACRO(create_doc_install filename targetdir)
   dune_common_script_dir(SCRIPT_DIR)

cmake/modules/DuneDoxygen.cmake

 # Module for building documentation using doxygen.
 #
-# provides the following macros:
+# .. cmake_function:: add_doxygen_target
 #
-# add_doxgen_target
+#    .. cmake_param:: TARGET
+#       :single:
 #
-# This macro creates a target for building (doxygen_${ProjectName}) and installing
-# (doxygen_install_${ProjectName}) the generated doxygen documentation.
-# The documentation is built during the top-level make doc call. We have added a dependency
-# that makes sure it is built before running make install.
+#       The suffix to add to the target name, default to the module name.
 #
+#    .. cmake_param:: DEPENDS
+#       :multi:
 #
+#       A list of further dependencies of the doxygen documentation.
+#       Might include :code:`mainpage.txt`.
+#
+#    .. cmake_param:: OUTPUT
+#       :single:
+#
+#       Name of the output target, necessary if you don't generate html.
+#
+#    This macro creates a target for building (:code:`doxygen_${ProjectName}`) and installing
+#    (:code:`doxygen_install_${ProjectName}`) the generated doxygen documentation.
+#    The documentation is built during the top-level :code:`make doc` call. We have added a dependency
+#    that makes sure it is built before running :code:`make install`.
+#
+
 FIND_PACKAGE(Doxygen)
 
 include (CMakeParseArguments)
@@ -37,19 +51,6 @@ MACRO (prepare_doxyfile)
   add_custom_target(Doxyfile DEPENDS Doxyfile.in Doxyfile)
 ENDMACRO (prepare_doxyfile)
 
-#
-# add_doxgen_target
-#
-# This macro creates a target for building (doxygen_${ProjectName}) and installing
-# (doxygen_install_${ProjectName}) the generated doxygen documentation.
-# The documentation is built during the top-level make doc call. We have added a dependency
-# that make sure it is built before running make install.
-#
-# the macro takes the following optional parameters:
-# TARGET [name]  : overwrite the target appendix, default is the module name
-# DEPENDS [list] : add a list of further dependencies for doxygen.
-#                  This list might include mainpage.txt
-# OUTPUT [name]  : change the name of the output target; necessary if you don't generate html.
 MACRO (add_doxygen_target)
   set(options )
   set(oneValueArgs TARGET OUTPUT)

cmake/modules/DuneEnableAllPackages.cmake

-# This module provides the functions necessary for a simplified CMake build system
-#
-# The DUNE build system relies on the user to choose and add the compile and link flags
-# necessary to build an executable. While this offers full control to the user, it
-# is an error-prone procedure.
-#
-# Alternatively, users may use the functions in this module to simply add the compile flags for all
-# found external modules to all executables in a DUNE module. Likewise, all found libraries are
-# linked to all targets.
-#
-# This module provides the following functions:
-#
-# dune_enable_all_packages(INCLUDE_DIRS [include_dirs]
-#                          COMPILE_DEFINITIONS [compile_definitions]
-#                          COMPILE_OPTIONS [compile_options]
-#                          MODULE_LIBRARIES [libraries]
-#                          [VERBOSE] [APPEND]
-#                          )
-#
-# Adds all flags and all libraries to all executables that are subsequently added in the directory
-# from where this function is called and from all its subdirectories (recursively).
-# If used, this function MUST be called in the top level CMakeLists.txt BEFORE adding any subdirectories!
-# You can optionally add additional include dirs and compile definitions that will also be applied to
-# all targets in the module.
-# Finally, if your module contains libraries as well as programs and if the programs should automatically
-# link to those libraries, you MUST list these libraries in MODULE_LIBRARIES. Those libraries will be
-# automatically created by dune_enable_all_packages (which internally calls dune_add_library()) and placed
-# in the lib/ directory. The order of the libraries matters: if one library depends on another one, it must
-# be listed after its dependency. This special handling of the libraries is due to the way newer CMake
-# versions handle linking (in particular CMP022 and CMP038). You can later add source files to the library
-# anywhere in the source tree by calling dune_library_add_sources().
-#
-# Warning: dune_enable_all_packages()  requires CMake 2.8.12+. If you call this function with an older version
-#          of CMake, the build will fail with a fatal error. DO NOT enable this feature if your module needs
-#          to compile on machines with an older version of CMake.
-# Warning: The library feature requires CMake 3.1+. If you use the feature with older versions, CMake
-#          will emit a fatal error. Moreover, it will issue a warning if the cmake_minimum_required()
+# Implementation of a simplified CMake build system.
+#
+# .. cmake_function:: dune_enable_all_packages
+#
+#    .. cmake_brief::
+#
+#       Previously, the DUNE build system relied on the user to choose and add the compile and link flags
+#       necessary to build an executable. While this offers full control to the user, it
+#       is an error-prone procedure.
+#
+#       Alternatively, users may use this function to simply add the compile flags for all
+#       found external modules to all executables in a DUNE module. Likewise, all found libraries are
+#       linked to all targets.
+#
+#    .. cmake_param:: INCLUDE_DIRS
+#       :multi:
+#
+#       A list of include directories, that should be added to all targets.
+#       In a standard Dune module, it is not necessary to specify anything.
+#
+#    .. cmake_param:: COMPILE_DEFINITIONS
+#       :multi:
+#
+#       A list of compile definitions, that should be added to all targets.
+#       In a standard Dune module, it is not necessary to specify anything.
+#
+#    .. cmake_param:: COMPILE_OPTIONS
+#       :multi:
+#
+#       A list of non-definition compile options, that should be added to all targets.
+#       In a standard Dune module, it is not necessary to specify anything.
+#
+#    .. cmake_param:: MODULE_LIBRARIES
+#       :multi:
+#
+#       If your module contains libraries as well as programs and if the programs should automatically
+#       link to those libraries, you *MUST* list these libraries in :code:`MODULE_LIBRARIES`. Those libraries will be
+#       automatically created by :ref:`dune_enable_all_packages` (which internally calls :ref:`dune_add_library()`) and placed
+#       in the lib/ directory. The order of the libraries matters: if one library depends on another one, it must
+#       be listed after its dependency. This special handling of the libraries is due to the way newer CMake
+#       versions handle linking (in particular CMP022 and CMP038). You can later add source files to the library
+#       anywhere in the source tree by calling :ref:`dune_library_add_sources()`.
+#
+#       .. warning::
+#          The library feature requires CMake 3.1+. If you use the feature with older versions, CMake
+#          will emit a fatal error. Moreover, it will issue a warning if the :code:`cmake_minimum_required`
 #          version is older than 3.1.
-# Note:    If you want to use dune_enable_all_packages() with an older version of CMake and your DUNE mdule
-#          creates its own library, you have to manually create the library in the top-level CMakeLists.txt
-#          file using dune_add_library() (with all sources listed within that call), use
-#          dune_target_enable_all_packages() to add all packages to the library and finally list that library
-#          under LIBRARIES in the call to dune_register_package_flags(). See dune-pdelab for an example of
-#          how to do this correctly.
 #
-# For a description of the APPEND option, see the documentation of dune_register_package_flags().
-# With the VERBOSE option set, the list of flags is printed during configure.
+#    .. cmake_param:: VERBOSE
+#       :option:
+#
+#       If this option is set, the set of compile flags, linked libraries and include directories
+#       that is in use for all targets in the module is printed upon configuration.
+#
+#    .. cmake_param:: APPEND
+#       :option:
+#
+#       If this option is set, the definitions, flags and directories specified in this function are
+#       appended to the global collection of flags instead of being prepended. Only use it, if you know
+#       what you are doing.
+#
+#    Adds all flags and all libraries to all executables that are subsequently added in the directory
+#    from where this function is called and from all its subdirectories (recursively).
+#    If used, this function *MUST* be called in the top level CMakeLists.txt BEFORE adding any subdirectories!
+#    You can optionally add additional include dirs and compile definitions that will also be applied to
+#    all targets in the module.
+#
+#    .. warning::
+#       :ref:`dune_enable_all_packages` requires CMake 2.8.12+. If you call this function with an older version
+#       of CMake, the build will fail with a fatal error. DO NOT enable this feature if your module needs
+#       to compile on machines with an older version of CMake.
+#
+#    .. note::
+#       If you want to use :code:`dune_enable_all_packages` with an older version of CMake and your DUNE module
+#       creates its own library, you have to manually create the library in the top-level CMakeLists.txt
+#       file using :ref:`dune_add_library` (with all sources listed within that call), use
+#       :ref:`dune_target_enable_all_packages` to add all packages to the library and finally list that library
+#       under :code:`LIBRARIES` in the call to :ref:`dune_register_package_flags`. See dune-pdelab for an example of
+#       how to do this correctly.
+#
+#    While :ref:`dune_enable_all_packages` defines the user interface for this feature, developers might
+#    also be interested in the following related functions:
+#
+#    * :ref:`dune_target_enable_all_packages`
+#    * :ref:`dune_register_package_flags`
+#    * :ref:`dune_library_add_sources`
+#
+# .. cmake_function:: dune_target_enable_all_packages
+#
+#    .. cmake_param:: TARGETS
+#       :multi:
+#
+#       A list of targets to add all flags etc. too.
+#
+#    Adds all currently registered package flags (see :ref:`dune_register_package_flags`) to the given targets.
+#    This function is mainly intended to help write DUNE modules that want to use :ref:`dune_enable_all_packages` and
+#    define their own libraries, but need to be compatible with CMake < 3.1
+#
+#    .. note::
+#       Just like :ref:`dune_enable_all_packages`, this function requires CMake 2.8.12+.
+#
+# .. cmake_function:: dune_register_package_flags
+#
+#    .. cmake_param:: INCLUDE_DIRS
+#       :multi:
+#
+#       The list of include directories needed by the external package.
+#
+#    .. cmake_param:: COMPILE_DEFINITIONS
+#       :multi:
+#
+#       The list of compile definitions needed by the external package.
+#
+#    .. cmake_param:: COMPILE_OPTIONS
+#       :multi:
+#
+#       The list of compile options needed by the external package.
+#
+#    .. cmake_param:: LIBRARIES
+#       :multi:
 #
+#       The list of libraries that the external package should link to.
+#       The order of the input is preserved in the output.
 #
-# dune_target_enable_all_packages(TARGETS [target] ...)
+#    .. cmake_param:: APPEND
+#       :option:
 #
-# Adds all currently registered package flags (see dune_register_package_flags()) to the given targets.
-# This function is mainly intended to help write DUNE modules that want to use dune_enable_all_packages() and
-# define their own libraries, but need to be compatible with CMake < 3.1.
+#       If this option is set, the definitions, flags and directories specified in this function are
+#       appended to the global collection of flags instead of being prepended. Only use it, if you know
+#       what you are doing.
 #
-# Note:    Just like dune_enable_all_packages(), this function requires CMake 2.8.12+.
+#    To correctly implement the automatic handling of external libraries, the compile flags, include paths and link
+#    flags of all found packages must be registered with this function. This function is only necessary for people that
+#    want to write their own :code:`FindFooBar` CMake modules to link against additional libraries which are not supported by
+#    the DUNE core modules. Call this function at the end of every find module. If you are using an external FindFoo
+#    module which you cannot alter, call it after the call to :code:`find_package(foo)`.
 #
+# .. cmake_function:: dune_library_add_sources
 #
-# dune_register_package_flags(COMPILE_DEFINITIONS [flags]
-#                             COMPILE_OPTIONS [options]
-#                             INCLUDE_DIRS {includes]
-#                             LIBRARIES [libs]
-#                             [APPEND]
-#                             )
+#    .. cmake_param:: module_library
+#       :single:
+#       :positional:
 #
-# To correctly implement the automatic handling of external libraries, the compile flags, include paths and link
-# flags of all found packages must be registered with this function. This function is only necessary for people that
-# want to write their own FindFooBar CMake modules to link against additional libraries which are not supported by
-# the DUNE core modules. Call this function at the end of every find module. If you are using an external FindFoo
-# module which you cannot alter, call it after the call to find_package(foo).
-# The APPEND parameter appends the given flags to the global list instead of prepending. Only use it, if you know
-# what you are doing.
+#       The name of the module library target.
 #
+#    .. cmake_param: SOURCES
+#       :multi:
+#       :required:
 #
-# dune_library_add_sources(module_library
-#                          SOURCES [sources]
-#                         )
+#       The source files to add to the DUNE module library :code:`module_library`.
+#       That library must have been created by an earlier call to :ref:`dune_enable_all_packages`
+#       in the current DUNE module.
 #
-# Adds the source files listed in [sources] to the DUNE module library module_library created by an earlier
-# call to dune_enable_all_packages() in the current DUNE module.
+#    Register sources for module exported library.
 #
 
 function(dune_register_package_flags)

cmake/modules/DuneMPI.cmake

@@ -10,13 +10,17 @@
 # compiler with MPI flags usually used for C. CXX bindings
 # are deactivated to prevent ABI problems.
 #
-# The following function is defined:
+# .. cmake_function:: add_dune_mpi_flags
 #
-# add_dune_mpi_flags(targets)
+#    .. cmake_param:: targets
+#       :single:
+#       :required:
+#       :positional:
 #
-# Adds the above flags and libraries to the specified targets.
+#       The target list to add the MPI flags to.
 #
 
+
 find_package(MPI)
 find_package(Threads)
 

cmake/modules/DuneMacros.cmake

 # Core DUNE module for CMake.
 #
-# Provides the following macros:
+# Documentation of the public API defined in this module:
+#
+# .. cmake_function:: dune_project
+#
+#    Initialize a Dune module. This function needs to be run from every
+#    top-level CMakeLists.txt file. It sets up the module, defines basic
+#    variables and manages depedencies. Don't forget to call
+#    :ref:`finalize_dune_project` afterwards.
+#
+# .. cmake_function:: finalize_dune_project
+#
+#    Finalize a Dune module. This function needs to be run at the end of
+#    every top-level CMakeLists.txt file.
+#
+# .. cmake_function:: dune_add_library
+#
+#    .. cmake_brief::
+#
+#       Add a library to a Dune module!
+#
+#    .. cmake_param:: basename
+#       :single:
+#       :required:
+#       :positional:
+#
+#       The basename for the library. On Unix this created :code:`lib<basename>.so`
+#       and :code:`lib<basename>.a`
+#
+#    .. cmake_param:: NO_EXPORT
+#       :option:
+#
+#       If omitted the library is exported for usage in other modules.
+#
+#    .. cmake_param:: ADD_LIBS
+#       :multi:
+#
+#       A list of libraries that should be incorporated into this library.
+#
+#    .. cmake_param:: OBJECT
+#       :option:
+#
+#       .. note::
+#          This feature will very likely vanish in Dune 3.0
+#
+#    .. cmake_param:: SOURCES
+#       :multi:
+#       :required:
+#
+#       The source files from which to build the library.
+#
+#    .. cmake_param:: COMPILE_FLAGS
+#       :multi:
+#
+#       Any additional compile flags fpr building the library.
+#
+# .. cmake_function:: dune_target_link_libraries
+#
+#    .. cmake_param:: BASENAME
+#
+#    .. cmake_param:: LIBRARIES
+#
+#    Link libraries to the static and shared version of
+#    library BASENAME
+#
+#
+# Documentation of internal macros in this module:
 #
 # dune_module_to_uppercase(upper_name module_name)
 #
@@ -13,15 +78,6 @@
 # Parse ${MODULE_DIR}/dune.module and provide that information.
 # If the second argument is QUIET no status message is printed.
 #
-#
-# dune_project()
-#
-#  macro that should be called near the begin of the top level CMakeLists.txt.
-# Namely it sets up the module, defines basic variables and manages
-# depedencies.
-# Don't forget to call finalize_dune_project afterwards.
-#
-#
 # dune_create_dependency_tree()
 #
 # Creates the dependency tree of the module.
@@ -35,7 +91,6 @@
 # _macro_name: variable where the name will be stored.
 # _dune_module: the name of the dune module.
 #
-#
 # dune_regenerate_config_cmake()
 #
 # Creates a new config_collected.h.cmake file in ${CMAKE_CURRENT_BINARY_DIR) that
@@ -44,37 +99,6 @@
 # of all dependent modules.
 # Finally config.h is created from config_collected.h.cmake.
 #
-#
-# dune_add_library(<basename> [NO_EXPORT] [ADD_LIBS <lib1> [<lib2> ...]]
-#   [OBJECT] SOURCES <source1> [<source2> ...] [COMPILE_FLAGS <flags>])
-#
-# Creates shared and static libraries with the same basename.
-# <basename> is the basename of the library.
-# On Unix this creates lib<basename>.so and lib<BASENAME>.a.
-# Libraries that should be incorporate into this library can
-# be specified with the ADD_LIBS option.
-# The libraries will be built in ${PROJECT_BINARY_DIR}/lib.
-# If the option NO_EXPORT is omitted the library is exported
-# for usage in other modules.
-#
-# Object libraries can now be created with dune_add_library(<target>
-#  OBJECT <sources>). It will create a GLOBAL property
-#  _DUNE_TARGET_OBJECTS:<target>_ that records the full path to the
-#  source files. Theses can later be referenced by providing
-#  _DUNE_TARGET_OBJECTS:<target>_ as one of the sources to dune_add_library
-#
-# finalize_dune_project()
-#
-# macro that should be called at the end of the top level CMakeLists.txt.
-# Namely it creates config.h and the cmake-config files,
-# some install directives and exports the module.
-#
-#
-# dune_target_link_libraries(BASENAME, LIBRARIES)
-#
-# Link libraries to the static and shared version of
-# library BASENAME
-#
 
 # Make CMake use rpath on OS X
 if(POLICY CMP0042)

cmake/modules/DuneSphinxCMakeDoc.cmake

+# Module to generate CMake API documentation with Sphinx
+#
+# .. cmake_function:: dune_cmake_sphinx_doc
+#
+#    .. cmake_brief::
+#
+#       Generate the documentation that you are just browsing!!!
+#
+#    .. cmake_param:: PATHS
+#       :multi:
+#
+#       The set of paths to look for CMake modules. Defaults
+#       to the cmake/modules subdirectory of the current module.
+#       Note, that all modules must be rst-documented following
+#       the criteria defined in :ref:`DuneSphinxCMakeDoc` in order
+#       to successfully generate documentation.
+#
+#    .. cmake_param:: BUILDTYPE
+#       :multi:
+#
+#       Set the type of build that is requested. By default, "html" is chosen.
+#       The list of available build types:
+#
+#       * `html`
+#
+#    .. cmake_param:: EXCLUDE
+#       :multi:
+#
+#       Exclude the given macros from the documentation.
+#
+#    .. cmake_param:: NO_DEFAULT_PATHS
+#       :option:
+#
+#       If set, the cmake/modules subdirectory will not be searched
+#       for CMake macros to generate documentation.
+#
+#    Generate a documentation for the CMake API. A set of cmake
+#    modules defined by the parameters and all functions and macros
+#    there in are automatically generated. The top level directory
+#    of the documentation is the current build directory (aka the
+#    directory that this function is called from)
+#
+#    There are some assumptions on how the documentation in
+#    the CMake modules is written:
+#
+#    * At the beginning of each CMake module there is a comment block that is written in restructured text.
+#      The first two characters of each line (the comment character
+#      and a blank) are ignored. Any resulting content of lines most form valid rst.
+#    * TODO document more
+#
+
+find_package(Sphinx)
+find_package(PythonInterp)
+
+
+function(dune_cmake_sphinx_doc)
+  # Only proceed if Sphinx was found on the system
+  if(NOT SPHINX_FOUND)
+    message("-- Skipping building CMake API documentation (Sphinx was not found!)")
+    return()
+  endif()
+
+  # Only proceed if the python interpreter was found by cmake
+  if(NOT PYTHONINTERP_FOUND)
+    message("-- Skipping building CMake API documentation (Python interpreter was not found!)")
+    return()
+  endif()
+
+  # Parse Arguments
+  set(OPTION NO_DEFAULT_PATHS)
+  set(SINGLE)
+  set(MULTI PATHS EXCLUDE BUILDTYPE)
+  include(CMakeParseArguments)
+  cmake_parse_arguments(SPHINX_CMAKE "${OPTION}" "${SINGLE}" "${MULTI}" ${ARGN})
+  if(SPHINX_CMAKE_UNPARSED_ARGUMENTS)
+    message(WARNING "Unparsed arguments in dune_cmake_sphinx_doc: This often indicates typos!")
+  endif()
+
+  # Apply defaults
+  if(NOT SPHINX_CMAKE_BUILDTYPE)
+    set(SPHINX_CMAKE_BUILDTYPE html)
+  endif()
+
+  # Add default paths to the path variable
+  if(NOT SPHINX_CMAKE_NO_DEFAULT_PATHS)
+    set(SPHINX_CMAKE_PATHS ${SPHINX_CMAKE_PATHS} ${CMAKE_SOURCE_DIR}/cmake/modules)
+  endif()
+
+  # Write the conf.py, which sets up Sphinx into the build
+  set(DUNE_SPHINX_EXT_PATH)
+  dune_common_script_dir(DUNE_SPHINX_EXT_PATH)
+  configure_file(${DUNE_SPHINX_EXT_PATH}/conf.py.in ${CMAKE_CURRENT_BINARY_DIR}/conf.py)
+
+  # Generate the list of modules by looking through the given paths
+  # for files matching *.cmake
+  set(SPHINX_DOC_MODULE_LIST)
+  foreach(path ${SPHINX_CMAKE_PATHS})
+    file(GLOB modules "${path}/*.cmake")
+    set(SPHINX_DOC_MODULE_LIST ${SPHINX_DOC_MODULE_LIST} ${modules})
+  endforeach()
+
+  # Initialize a variable that collects all dependencies of the documentation
+  set(DOC_DEPENDENCIES)
+
+  # Generate the rst files for all cmake modules
+  foreach(module ${SPHINX_DOC_MODULE_LIST})
+    get_filename_component(modname ${module} NAME)
+    add_custom_command(OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/modules/${modname}
+                       COMMAND ${PYTHON_EXECUTABLE} ${DUNE_SPHINX_EXT_PATH}/extract_cmake_data.py
+                         --module=${module}
+                         --builddir=${CMAKE_CURRENT_BINARY_DIR}
+                       DEPENDS ${module})
+    set(DOC_DEPENDENCIES ${DOC_DEPENDENCIES} ${CMAKE_CURRENT_BINARY_DIR}/modules/${modname})
+  endforeach()
+
+  # copy the rst files that are fixed to the build directory during configure
+  file(GLOB rstfiles "${CMAKE_CURRENT_SOURCE_DIR}/*.rst")
+  foreach(rst ${rstfiles})
+    get_filename_component(rstname ${rst} NAME)
+    add_custom_command(OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/${rstname}
+                       COMMAND ${CMAKE_COMMAND} -E copy ${rst} ${CMAKE_CURRENT_BINARY_DIR}
+                       DEPENDS ${rst})
+    set(DOC_DEPENDENCIES ${DOC_DEPENDENCIES} ${CMAKE_CURRENT_BINARY_DIR}/${rstname})
+  endforeach()
+
+  # Call Sphinx once for each requested build type
+  foreach(type ${SPHINX_CMAKE_BUILDTYPE})
+    # Call the sphinx executable
+    add_custom_target(sphinx_${type}
+                      COMMAND ${SPHINX_EXECUTABLE}
+                                -b ${type}
+                                -w ${CMAKE_BINARY_DIR}/SphinxError.log
+                                -c ${CMAKE_CURRENT_BINARY_DIR}
+                                ${CMAKE_CURRENT_BINARY_DIR}
+                                ${CMAKE_CURRENT_BINARY_DIR}/${type}
+                      WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
+                      DEPENDS ${DOC_DEPENDENCIES}
+                     )
+    add_dependencies(doc sphinx_${type})
+  endforeach()
+endfunction()

cmake/modules/DuneStreams.cmake

-# Module configures the DUNE debug streams.
-# A default debug level can be specified with
-# MINIMAL_DEBUG_LEVEL
+# This Module configures the DUNE debug streams.
 #
+# .. cmake_variable:: MINIMAL_DEBUG_LEVEL
+#
+#    This variable configures the Dune debug streams.
+#    Standard debug streams with level below :code:`MINIMAL_DEBUG_LEVEL` will
+#    collapse to doing nothing if output is requested. Possible values are
+#    :code:`vverb`, :code:`verb`, :code:`info`, :code:`warn` and :code:`grave`.
+#    Deafults to :code:`warn`.
+#
+
 macro(dune_set_minimal_debug_level)
 set(MINIMAL_DEBUG_LEVEL ON CACHE STRING "set the MINIMAL_DEBUG_LEVEL. Standard debug streams with level below MINIMAL_DEBUG_LEVEL will collapse to doing nothing if output is requested. (default=warn)")
 set_property(CACHE MINIMAL_DEBUG_LEVEL PROPERTY STRINGS

cmake/modules/DuneSymlinkOrCopy.cmake

@@ -27,21 +27,82 @@
 # in the source tree. This file will be copied
 # to the build tree.
 #
-#   dune_symlink_to_source_tree([NAME name])
 #
-# add a symlink called NAME to all directories in the build tree (defaults to src_dir).
-# That symlink points to the corresponding directory in the source tree.
-# Call the macro from the toplevel CMakeLists.txt file of your project.
-# You can also call it from some other directory, creating only symlinks
-# in that directory and all directories below. A warning is issued on
-# Windows systems.
+# .. cmake_function:: dune_add_copy_command
 #
-#   dune_symlink_to_source_files(FILES files)
+#    .. cmake_param:: filename
+#       :positional:
+#       :single:
+#       :required:
+#
+#    .. todo::
+#       DOC ME!
+#
+# .. cmake_function:: dune_add_copy_target
+#
+#    .. cmake_param:: target_name
+#       :positional:
+#       :single:
+#       :required:
+#
+#    .. cmake_param:: filename
+#       :positional:
+#       :single:
+#       :required:
+#
+#    .. todo::
+#       DOC ME!
+#
+# .. cmake_function:: dune_add_copy_dependency
+#
+#    .. cmake_param:: target
+#       :positional:
+#       :single:
+#       :required:
+#
+#    .. cmake_param:: filename
+#       :positional:
+#       :single:
+#       :required:
+#
+#    .. todo::
+#       DOC ME!
+#
+# .. cmake_function:: dune_symlink_to_source_tree
+#
+#    .. cmake_param:: NAME
+#       :single:
+#
+#       The name of the symlink, defaults to :code:`src_dir`.
+#
+#    This function will place a symlink into every subdirectory
+#    of the build tree, that allows to jump to the corresponding
+#    source directory. Call this from your top-level :code:`CMakeLists.txt`
+#    to enable it for a given module. To enable it for all modules,
+#    set the variable :ref:`DUNE_SYMLINK_TO_SOURCE_TREE` instead.
+#    If used on Windows systems, a warning is issued.
+#
+# .. cmake_variable:: DUNE_SYMLINK_TO_SOURCE_TREE
+#
+#    If this variable is set to TRUE, the functionality of
+#    :ref:`dune_symlink_to_source_tree` is enabled in all modules.
+#    This will place symlinks to the corresponding source directory
+#    in every subdirectory of the build directory.
+#
+# .. cmake_function:: dune_symlink_to_source_files
+#
+#    .. cmake_param:: FILES
+#       :multi:
+#       :required:
+#
+#       The list of files to symlink.
+#
+#    Create symlinks in the current build directory, which
+#    point to files in the source directory. This is usually
+#    used for grid and ini files and the like. On Windows systems,
+#    a warning is issued and copying is used as a fallback to
+#    symlinking.
 #
-# add symlinks to the build tree, which point to files in the source tree.
-# Foreach file given in "files", a symlink of that name is created in the
-# corresponding build directory. Use for ini files, grid files etc. A warning
-# is issued on Windows systems.
 
 macro(dune_add_copy_command file_name)
     add_custom_command(

cmake/modules/FindGMP.cmake

-# Module that checks for the GNU MP Bignum (GMP) library, include
-# dirs and
+# .. cmake_module::
 #
-# Variables used by this module which you may want to set:
-# GMP_ROOT Path list to search for GMP
+#    Find the GNU MP Bignum (GMP) library
 #
-# Sets the following variables:
-# GMP_FOUND True if the GMP library was found.
+#    You may set the following variables to modify the
+#    behaviour of this module:
 #
+#    :ref:`GMP_ROOT`
+#       Path list to search for GMP
+#
+#    Sets the following variables:
+#
+#    :code:`GMP_FOUND`
+#       True if the GMP library was found.
+#
+# .. cmake_variable:: GMP_ROOT
+#
+#   You may set this variable to have :ref:`FindGMP` look
+#   for the gmp package in the given path before inspecting
+#   system paths.
+#
+
 
 # search for location of header gmpxx.h", only at positions given by the user
 find_path(GMP_INCLUDE_DIR