diff --git a/.gitignore b/.gitignore
index 1e4ad6c5fa5b4c67b74083b0a7793f598ba2cecb..790258ad271e47701845399d0f2675a975c41493 100644
--- a/.gitignore
+++ b/.gitignore
@@ -5,6 +5,7 @@
*.o
*.trs
*~
+*.pyc
.deps/
.libs/
Makefile
diff --git a/cmake/modules/AddGMPFlags.cmake b/cmake/modules/AddGMPFlags.cmake
index a5794268db48a549abb0f60e7782748ffccffdfa..e004ff006a7e4af584fbe2caf0c4f0daa2bd841f 100644
--- a/cmake/modules/AddGMPFlags.cmake
+++ b/cmake/modules/AddGMPFlags.cmake
@@ -1,6 +1,16 @@
-# 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})
diff --git a/cmake/modules/AddMETISFlags.cmake b/cmake/modules/AddMETISFlags.cmake
index 9cfe3389c472f40eb9c9c2be94ebdf4b8ebc2cda..cc65324af44fa909e6c406c9ca9e8980e058cb3c 100644
--- a/cmake/modules/AddMETISFlags.cmake
+++ b/cmake/modules/AddMETISFlags.cmake
@@ -1,11 +1,16 @@
-# 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})
diff --git a/cmake/modules/AddPTScotchFlags.cmake b/cmake/modules/AddPTScotchFlags.cmake
index f1ae6fabeca8165a555f986156eacd383a9232ec..7365c1aabfffe2337e869cda8cba1333f444697a 100644
--- a/cmake/modules/AddPTScotchFlags.cmake
+++ b/cmake/modules/AddPTScotchFlags.cmake
@@ -1,11 +1,16 @@
-# 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})
diff --git a/cmake/modules/AddParMETISFlags.cmake b/cmake/modules/AddParMETISFlags.cmake
index c311e74bcbb6d564a74636a888848d49861b0c56..bf0842a076cf70ffa6c65da4b2f5c917a20ef140 100644
--- a/cmake/modules/AddParMETISFlags.cmake
+++ b/cmake/modules/AddParMETISFlags.cmake
@@ -1,11 +1,16 @@
-# 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})
diff --git a/cmake/modules/AddUMFPackFlags.cmake b/cmake/modules/AddUMFPackFlags.cmake
index 5ed6cdc2b45dcb5b8c18004db04d65c677f0cadb..02a3bfa845950d82ebb3b013e644ae2013274e14 100644
--- a/cmake/modules/AddUMFPackFlags.cmake
+++ b/cmake/modules/AddUMFPackFlags.cmake
@@ -1,10 +1,16 @@
-# 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)
diff --git a/cmake/modules/CMakeLists.txt b/cmake/modules/CMakeLists.txt
index 77362f51f87b6f7ae87c19a28edf539d8fe6264a..7ca173e642f0b91adbfbdc96d4360693beab106a 100644
--- a/cmake/modules/CMakeLists.txt
+++ b/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
diff --git a/cmake/modules/CheckCXXFeatures.cmake b/cmake/modules/CheckCXXFeatures.cmake
index b22f363df80713b1299923d7f7c91c8ae75a5c4f..746e2a72b0c52d071d602d83fe346f8eabcaf2fa 100644
--- a/cmake/modules/CheckCXXFeatures.cmake
+++ b/cmake/modules/CheckCXXFeatures.cmake
@@ -1,20 +1,45 @@
+# .. 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()
diff --git a/cmake/modules/DuneCMakePackageConfigHelpers.cmake b/cmake/modules/DuneCMakePackageConfigHelpers.cmake
index 330babc6f4b3b93aef9bdc0818429c5ba9fc2caa..1ad1b023a1d41b10fa8f38990ce58b2184a47579 100644
--- a/cmake/modules/DuneCMakePackageConfigHelpers.cmake
+++ b/cmake/modules/DuneCMakePackageConfigHelpers.cmake
@@ -1,3 +1,7 @@
+# .. 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.
diff --git a/cmake/modules/DuneCommonMacros.cmake b/cmake/modules/DuneCommonMacros.cmake
index 84b69d45ab8e20e6c1cd84f8611cd6065867bb8a..b5a04bef1d803b277fd0730574734e0f86539b55 100644
--- a/cmake/modules/DuneCommonMacros.cmake
+++ b/cmake/modules/DuneCommonMacros.cmake
@@ -1,10 +1,8 @@
-# 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()
diff --git a/cmake/modules/DuneCxaDemangle.cmake b/cmake/modules/DuneCxaDemangle.cmake
index 7909a677591ef4ba65dc17fc8a02053d7c8989da..39f126c5d3ecb9d903586ba26a8eff3e11563d61 100644
--- a/cmake/modules/DuneCxaDemangle.cmake
+++ b/cmake/modules/DuneCxaDemangle.cmake
@@ -1,11 +1,10 @@
-# 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>
diff --git a/cmake/modules/DuneDoc.cmake b/cmake/modules/DuneDoc.cmake
index 200f8f812f1e1520dfafe9a967f2ae87829fbb5d..ddeb8bb5324cd1814f06676aa31fec836f7323f8 100644
--- a/cmake/modules/DuneDoc.cmake
+++ b/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)
diff --git a/cmake/modules/DuneDoxygen.cmake b/cmake/modules/DuneDoxygen.cmake
index 3bcb57bdaf512d4f8266e3e863353da1c38141d1..7d014a2a45a0c0686d2dd82551c1d700bec875f9 100644
--- a/cmake/modules/DuneDoxygen.cmake
+++ b/cmake/modules/DuneDoxygen.cmake
@@ -1,15 +1,29 @@
# 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)
diff --git a/cmake/modules/DuneEnableAllPackages.cmake b/cmake/modules/DuneEnableAllPackages.cmake
index 532f9ce28ef47abec724590f628a5ea41dedf3fe..960600a15eb1c2d654e76df25767c8e293b5d43e 100644
--- a/cmake/modules/DuneEnableAllPackages.cmake
+++ b/cmake/modules/DuneEnableAllPackages.cmake
@@ -1,83 +1,157 @@
-# 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)
diff --git a/cmake/modules/DuneMPI.cmake b/cmake/modules/DuneMPI.cmake
index 4ea6d69331da7eabf6a9b8e3e660aadd9eb8cd9f..07bc9445651996f0bb38f1fd0fcd928d60f848da 100644
--- a/cmake/modules/DuneMPI.cmake
+++ b/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)
diff --git a/cmake/modules/DuneMacros.cmake b/cmake/modules/DuneMacros.cmake
index 8b6a7812e6eb4999e75a75d106c79a930982a7bd..b1b1843c13cd126ec1a38b0b6b74a586d86d029e 100644
--- a/cmake/modules/DuneMacros.cmake
+++ b/cmake/modules/DuneMacros.cmake
@@ -1,6 +1,71 @@
# 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)
diff --git a/cmake/modules/DuneSphinxCMakeDoc.cmake b/cmake/modules/DuneSphinxCMakeDoc.cmake
new file mode 100644
index 0000000000000000000000000000000000000000..47b84d7b8421212c85a09bb5a3c208553da87a2f
--- /dev/null
+++ b/cmake/modules/DuneSphinxCMakeDoc.cmake
@@ -0,0 +1,141 @@
+# 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()
diff --git a/cmake/modules/DuneStreams.cmake b/cmake/modules/DuneStreams.cmake
index bd1f5068b4a30ad48077a4f1e52df197c329fb9a..501aaa1d7ba67a092c4ace99ad642120ec06be2b 100644
--- a/cmake/modules/DuneStreams.cmake
+++ b/cmake/modules/DuneStreams.cmake
@@ -1,7 +1,14 @@
-# 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
diff --git a/cmake/modules/DuneSymlinkOrCopy.cmake b/cmake/modules/DuneSymlinkOrCopy.cmake
index 86a038c372f84c7c411e932b64b778307020c467..860a563898b27257a514ceb5b2258a0a0071d4ab 100644
--- a/cmake/modules/DuneSymlinkOrCopy.cmake
+++ b/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(
diff --git a/cmake/modules/FindGMP.cmake b/cmake/modules/FindGMP.cmake
index 8559f8ae26344de17c404257189b8391f3d454ed..22ddf8c2ea7109d76897f7f8745eb5d8e2b82b1a 100644
--- a/cmake/modules/FindGMP.cmake
+++ b/cmake/modules/FindGMP.cmake
@@ -1,12 +1,25 @@
-# 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
diff --git a/cmake/modules/FindInkscape.cmake b/cmake/modules/FindInkscape.cmake
index 8ebfc9fbdaead7fa15a49ea6136f63a9bb8914e5..c3561d5fa2cdac8a7a18a5ead28f7ec4fd831f5a 100644
--- a/cmake/modules/FindInkscape.cmake
+++ b/cmake/modules/FindInkscape.cmake
@@ -1,16 +1,15 @@
-# Module that checks for inkscape
+# .. cmake_module::
#
-# Sets the following variables
+# Module that checks for inkscape
#
-# INSCAPE: Path to inkscape to generate .png's form .svg's
+# Sets the following variables
#
-# Provides the following functions:
+# :code:`INKSCAPE_FOUND`
+# Whether inkscape was found
#
-# inkscape_generate_png_from_svg([OUTPUT_DIR <output_dir>] <pngfile1.png> [<pngfile2.png> ....])
+# :code:`INKSCAPE`
+# Path to inkscape to generate .png's form .svg's
#
-# Generates pngfile1, ... from svg input files pngfile1.svg, ....
-# The output directory can be specified with the option OUTPUT_DIR. If it is omitted
-# the files will be generated in CMAKE_CURRENT_BINARY_DIR.
find_program(INKSCAPE inkscape DOC "Path to inkscape to generate png files from svg files")
find_program(CONVERT convert DOC "Path to convert program")
diff --git a/cmake/modules/FindMETIS.cmake b/cmake/modules/FindMETIS.cmake
index 77ca3543e713afa3a22bd47e7e9125b7943405d4..fc2b88442bc4b7de3d4bc1d58c6f65140a73d182 100644
--- a/cmake/modules/FindMETIS.cmake
+++ b/cmake/modules/FindMETIS.cmake
@@ -1,21 +1,46 @@
-# Accepts the following variables:
+# .. cmake_module::
#
-# METIS_ROOT: Prefix where METIS is installed.
-# METIS_LIB_NAME: Name of the METIS library (default: metis).
-# METIS_LIBRARY: Full path of the METIS library.
-
-# Sets the following variables:
+# Find the METIS library
#
-# METIS_LIBRARY: Full path of the METIS library.
-# METIS_FOUND: True if ParMETIS was found.
-# METIS_LIBRARIES: List of all libraries needed for linking with METIS,
+# You may set the following variables to modify the
+# behaviour of this module:
#
-# Provides the following macros:
+# :ref:`METIS_ROOT`
+# Prefix, where METIS is installed
#
-# find_package(METIS)
+# :ref:`METIS_LIBNAME`
+# Name of the METIS library (default: metis)
+#
+# :ref:`METIS_LIBRARY`
+# Full path to the METIS library
+#
+# Sets the following variables:
+#
+# :code:`METIS_FOUND`
+# True if the METIS library was found.
+#
+# :code:`METIS_LIBRARY`
+# Full path to the METIS library
+#
+# :code:`METIS_LIBRARIES`
+# List of libraries needed for linking with METIS
+#
+# .. cmake_variable:: METIS_ROOT
+#
+# You may set this variable to have :ref:`FindMETIS` look
+# for the METIS library and includes in the given path
+# before inspecting default system paths.
+#
+# .. cmake_variable:: METIS_LIBNAME
+#
+# You may set this variable to specify the name of the METIS
+# library that :ref:`FindMETIS` looks for.
+#
+# .. cmake_variable:: METIS_LIBRARY
+#
+# You may set this variable to specify the full path to the METIS
+# library, that should be used by :ref:`FindMETIS`.
#
-# Searches for METIS (See above)
-
# search metis header
find_path(METIS_INCLUDE_DIR metis.h
diff --git a/cmake/modules/FindMProtect.cmake b/cmake/modules/FindMProtect.cmake
index 779c9a9a8ae649608dfb1857ea881d3c9918beb8..75b3fcba7b3cad6673809404482a8754cbd6dcc6 100644
--- a/cmake/modules/FindMProtect.cmake
+++ b/cmake/modules/FindMProtect.cmake
@@ -1,9 +1,13 @@
+# .. cmake_module::
#
-# Module that detects mproctect support
+# Module that detects mprotect support
#
-# Sets the following variables
-# HAVE_SYS_MMAN_H
-# HAVE_MPROTECT
+# Sets the following variables:
+#
+# * :code:`HAVE_SYS_MMAN_H`
+# * :code:`HAVE_MPROTECT`
+#
+
include(CheckIncludeFile)
check_include_file("sys/mman.h" HAVE_SYS_MMAN_H)
include(CheckCSourceCompiles)
diff --git a/cmake/modules/FindPTScotch.cmake b/cmake/modules/FindPTScotch.cmake
index 4a809debba82965e5d107fb15a47f4a9435696a4..b1670eb140e61a4b417fddbcb2a1808ff0623b0b 100644
--- a/cmake/modules/FindPTScotch.cmake
+++ b/cmake/modules/FindPTScotch.cmake
@@ -1,22 +1,34 @@
-# Module that checks whether PT-Scotch is available.
+# .. cmake_module::
#
-# Accepts the following variables:
+# Module that checks whether PT-Scotch is available.
#
-# PTSCOTCH_ROOT: Prefix where PT-Scotch is installed.
-# PTSCOTCH_SUFFIX: Scotch might be compiled using different
-# integer sizes (int32, int64, long). When
-# this is is set the headers and libaries
-# are search under the suffix
-# include/scotch-${PTSCOTCH_SUFFIX}, and
-# lib/scotch-${PTSCOTCH_SUFFIX}, respectively.
-# Sets the following variables:
-# PTSCOTCH_INCLUDE_DIRS: All include directories needed to compile PT-Scotch programs.
-# PTSCOTCH_LIBRARIES: Alle libraries needed to link PT-Scotch programs.
-# PTSCOTCH_FOUND: True if PT-Scotch was found.
+# You may set the following variables to customize this modules behaviour:
#
-# Provides the following macros:
+# :ref:`PTSCOTCH_ROOT`
+# Prefix where PT-Scotch is installed.
+#
+# :ref:`PTSCOTCH_SUFFIX`
+# Scotch might be compiled using different
+# integer sizes (int32, int64, long). When
+# this is is set the headers and libaries
+# are search under the suffix
+# :code:`include/scotch-${PTSCOTCH_SUFFIX}`, and
+# :code:`lib/scotch-${PTSCOTCH_SUFFIX}`, respectively.
+#
+# This module sets the following variables:
+#
+# :code:`PTSCOTCH_FOUND`
+# True if PT-Scotch was found.
+#
+# :code:`PTSCOTCH_INCLUDE_DIRS`
+# All include directories needed to compile PT-Scotch programs.
+#
+# :code:`PTSCOTCH_LIBRARIES`
+# All libraries needed to link PT-Scotch programs.
+#
+# :code:`PTSCOTCH_FOUND`
+# True if PT-Scotch was found.
#
-# find_package(PTScotch)
include(DuneMPI)
macro(_search_pt_lib libvar libname doc)
diff --git a/cmake/modules/FindParMETIS.cmake b/cmake/modules/FindParMETIS.cmake
index 010d9c7f36368364bd303ede9191902e242d07ef..2b7d1d469472e8e57d48162bd3b84a675f4d8d61 100644
--- a/cmake/modules/FindParMETIS.cmake
+++ b/cmake/modules/FindParMETIS.cmake
@@ -1,23 +1,55 @@
-# Module that checks whether ParMETIS is available.
+# .. cmake_module::
#
-# Accepts the following variables:
+# Module that checks whether ParMETIS is available.
#
-# PARMETIS_ROOT: Prefix where ParMETIS is installed.
-# METIS_LIB_NAME: Name of the METIS library (default: metis).
-# PARMETIS_LIB_NAME: Name of the ParMETIS library (default: parmetis).
-# METIS_LIBRARY: Full path of the METIS library.
-# PARMETIS_LIBRARY: Full path of the ParMETIS library
-
-# Sets the following variables:
+# You may set the following variables to configure this modules behaviour:
+#
+# :ref:`PARMETIS_ROOT`
+# Prefix where ParMETIS is installed.
+#
+# :ref:`METIS_LIB_NAME`
+# Name of the METIS library (default: metis).
+#
+# :ref:`PARMETIS_LIB_NAME`
+# Name of the ParMETIS library (default: parmetis).
+#
+# :ref:`METIS_LIBRARY`
+# Full path of the METIS library.
+#
+# :ref:`PARMETIS_LIBRARY`
+# Full path of the ParMETIS library
+#
+# Sets the following variables:
+#
+# :code:`PARMETIS_FOUND`
+# True if ParMETIS was found.
#
-# METIS_LIBRARY: Full path of the METIS library.
-# PARMETIS_LIBRARY: Full path of the ParMETIS library.
-# PARMETIS_FOUND: True if ParMETIS was found.
-# PARMETIS_LIBRARIES: List of all libraries needed for linking with ParMETIS,
+# :code:`METIS_LIBRARY`
+# Full path of the METIS library.
#
-# Provides the following macros:
+# :code:`PARMETIS_LIBRARY`
+# Full path of the ParMETIS library.
#
-# find_package(ParMETIS)
+# :code:`PARMETIS_LIBRARIES`
+# List of all libraries needed for linking with ParMETIS,
+#
+# .. cmake_variable:: PARMETIS_ROOT
+#
+# You may set this variable to have :ref:`FindParMETIS` look
+# for the ParMETIS library and includes in the given path
+# before inspecting default system paths.
+#
+# .. cmake_variable:: PARMETIS_LIB_NAME
+#
+# You may set this variable to specify the name of the ParMETIS
+# library that :ref:`FindParMETIS` looks for.
+#
+# .. cmake_variable:: PARMETIS_LIBRARY
+#
+# You may set this variable to specify the full path to the ParMETIS
+# library, that should be used by :ref:`FindParMETIS`.
+#
+
find_path(PARMETIS_INCLUDE_DIR parmetis.h
PATHS ${PARMETIS_DIR} ${PARMETIS_ROOT}
diff --git a/cmake/modules/FindSphinx.cmake b/cmake/modules/FindSphinx.cmake
new file mode 100644
index 0000000000000000000000000000000000000000..718e20d7556077600cd5ff03ede03c96dce5c8a1
--- /dev/null
+++ b/cmake/modules/FindSphinx.cmake
@@ -0,0 +1,41 @@
+# .. cmake_module::
+#
+# Find Sphinx - the python documentation tool
+#
+# You may set the following variables to modify the
+# behaviour of this module:
+#
+# :ref:`SPHINX_ROOT`
+# the path to look for sphinx with the highest priority
+#
+# The following variables are set by this module:
+#
+# :code:`SPHINX_FOUND`
+# whether Sphinx was found
+#
+# :code:`SPHINX_EXECUTABLE`
+# the path to the sphinx-build executable
+#
+# .. cmake_variable:: SPHINX_ROOT
+#
+# You may set this variable to have :ref:`FindSphinx` look
+# for the :code:`sphinx-build` executable in the given path
+# before inspecting system paths.
+#
+
+#TODO export version.
+
+find_program(SPHINX_EXECUTABLE
+ NAMES sphinx-build
+ PATHS ${SPHINX_ROOT}
+ NO_DEFAULT_PATH)
+
+find_program(SPHINX_EXECUTABLE
+ NAMES sphinx-build)
+
+include(FindPackageHandleStandardArgs)
+find_package_handle_standard_args(
+ "Sphinx"
+ DEFAULT_MSG
+ SPHINX_EXECUTABLE
+)
diff --git a/cmake/modules/FindThreadsCMake31.cmake b/cmake/modules/FindThreadsCMake31.cmake
index 8174e2b15ce421c292e40f266d49c412b23832f2..ac96e3bb7f7628d3967f3ee656f4fd7147197a7f 100644
--- a/cmake/modules/FindThreadsCMake31.cmake
+++ b/cmake/modules/FindThreadsCMake31.cmake
@@ -1,45 +1,38 @@
-#.rst:
-# FindThreads
-# -----------
+# .. cmake_module::
#
-# This module determines the thread library of the system.
+# This module determines the thread library of the system.
#
-# This file is a modified copy from CMake 3.1. Do not edit this
-# file. Remove this file once we rely on at least CMake 3.1.
+# This file is a modified copy from CMake 3.1. Do not edit this
+# file. Remove this file once we rely on at least CMake 3.1.
#
-# The following variables are set
+# The following variables are set
#
-# ::
+# :code:`CMAKE_THREAD_LIBS_INIT`
+# the thread library
#
-# CMAKE_THREAD_LIBS_INIT - the thread library
-# CMAKE_USE_SPROC_INIT - are we using sproc?
-# CMAKE_USE_WIN32_THREADS_INIT - using WIN32 threads?
-# CMAKE_USE_PTHREADS_INIT - are we using pthreads
-# CMAKE_HP_PTHREADS_INIT - are we using hp pthreads
+# :code:`CMAKE_USE_SPROC_INIT`
+# are we using sproc?
#
-# The following import target is created
+# :code:`CMAKE_USE_WIN32_THREADS_INIT`
+# using WIN32 threads?
#
-# ::
+# :code:`CMAKE_USE_PTHREADS_INIT`
+# are we using pthreads
#
-# Threads::Threads
+# :code:`CMAKE_HP_PTHREADS_INIT`
+# are we using hp pthreads
#
-# For systems with multiple thread libraries, caller can set
+# .. cmake_variable:: CMAKE_THREAD_PREFER_PTHREAD
#
-# ::
+# For systems with multiple thread libraries, caller can set this
+# variable to prefer pthread. Modifies the behaviour of :ref:`FindThreadsCMake31.cmake`.
#
-# CMAKE_THREAD_PREFER_PTHREAD
+# .. cmake_variable:: THREADS_PREFER_PTHREAD_FLAG
#
-# If the use of the -pthread compiler and linker flag is prefered then the
-# caller can set
-#
-# ::
-#
-# THREADS_PREFER_PTHREAD_FLAG
-#
-# Please note that the compiler flag can only be used with the imported
-# target. Use of both the imported target as well as this switch is highly
-# recommended for new code.
+# If the use of the -pthread compiler and linker flag is prefered then the
+# caller can set this variable. Modifies the behaviour of :ref:`FindThreadsCMake31.cmake`.
#
+
#=============================================================================
# CMake - Cross Platform Makefile Generator
# Copyright 2000-2015 Kitware, Inc.
diff --git a/cmake/modules/FindUMFPack.cmake b/cmake/modules/FindUMFPack.cmake
index c25ba6a37c4f668a1d005c5833c3bb5fe10b3c4a..4e68fcb56a48996cd9a1ba8c492d388bcc2b8be9 100644
--- a/cmake/modules/FindUMFPack.cmake
+++ b/cmake/modules/FindUMFPack.cmake
@@ -1,13 +1,29 @@
-# Module that checks whether UMFPack is available.
+# .. cmake_module::
#
-# Variables used by this module which you may want to set:
-# UMFPACK_ROOT Path list to search for UMFPack
+# Find the UMFPack library
#
-# Sets the following variables
+# You may set the following variables to modify the
+# behaviour of this module:
#
-# UMFPACK_FOUND True if UMFPack was found and usable
-# UMFPACK_INCLUDE_DIRS Path to the UMFPack include dirs
-# UMFPACK_LIBRARIES Name of the UMFPack libraries
+# :ref:`UMFPACK_ROOT`
+# Path list to search for UMFPack.
+#
+# Sets the following variables:
+#
+# :code:`UMFPACK_FOUND`
+# True if the GMP library was found.
+#
+# :code:`UMFPACK_INCLUDE_DIRS`
+# List of include directories with the UMFPack headers
+#
+# :code:`UMFPACK_LIBRARIES`
+# List of libraries to link with UMFPack.
+#
+# .. cmake_variable:: UMFPACK_ROOT
+#
+# You may set this variable to have :ref:`FindUMFPack` look
+# for the UMFPack package in the given path before inspecting
+# system paths.
#
find_package(BLAS QUIET REQUIRED)
diff --git a/cmake/modules/Headercheck.cmake b/cmake/modules/Headercheck.cmake
index 2f4db5059850b9b7847e1528f20d340d45967a22..156fb2ca9cfd259380df536bd691849edfcb374f 100644
--- a/cmake/modules/Headercheck.cmake
+++ b/cmake/modules/Headercheck.cmake
@@ -1,3 +1,11 @@
+# .. cmake_variable:: ENABLE_HEADERCHECK
+#
+# Set this variable to TRUE if you want to use the CMake
+# reimplementation of the old autotools feaure :code:`make headercheck`.
+# There has been a couple of issues with this implementation in
+# the past, so it was deactivated by default.
+#
+
# sets up a global property with the names of all header files
# in the module and a global target depending on all checks
macro(setup_headercheck)
diff --git a/cmake/modules/OverloadCompilerFlags.cmake b/cmake/modules/OverloadCompilerFlags.cmake
index d3a975dd6f874bb2120a3363f9e89b5b1554be4f..b41dfa6e9b07b1a458e252e6861295fe67772703 100644
--- a/cmake/modules/OverloadCompilerFlags.cmake
+++ b/cmake/modules/OverloadCompilerFlags.cmake
@@ -5,16 +5,24 @@
# initialize_compiler_script() : needs to be called before further flags are added to CMAKE_CXX_FLAGS
# finalize_compiler_script() : needs to be called at the end of the cmake macros, e.g. in finalize_dune_project
#
-# By default this feature is disabled. Use -DALLOW_CXXFLAGS_OVERWRITE=ON to activate.
-# Then the following is possible:
+# Those two macro calls are hooked into dune_project/finalize_dune_project.
#
-# make CXXFLAGS="your flags" GRIDTYPE="grid type"
+# .. cmake_variable:: ALLOW_CXXFLAGS_OVERWRITE
#
-# GRIDTYPE can be anything defined in config.h via the dune_define_gridtype macro from dune-grid.
-# Furthermore any CPP variable of the form -DVAR=VALUE can be overloaded on the command line.
+# Setting this option will allow you to overload preprocessor definitions from
+# the command line, as it was possible naturally with the autotools build system.
+# This feature only works with a :code:`Unix Makefiles` based generator. You can
+# use it as:
#
-# Note: If you don't know what this is or what it's good for, don't use it.
+# :code:`make CXXFLAGS="your flags" GRIDTYPE="grid type"`
#
+# :code:`GRIDTYPE` can be anything defined in :code:`config.h` via the :ref:`dune_define_gridtype` macro from dune-grid.
+# Furthermore any CPP variable of the form :code:`-DVAR=VALUE` can be overloaded on the command line.
+#
+# .. note::
+# If you don't know what this is or what it's good for, don't use it.
+#
+
option(ALLOW_CXXFLAGS_OVERWRITE OFF)
macro(find_extended_unix_commands)
diff --git a/cmake/modules/UseInkscape.cmake b/cmake/modules/UseInkscape.cmake
index 0746a0a1b9604511623c83858c277c71251a07a4..26c2a23b06d96129b55818b3d14653018e126f44 100644
--- a/cmake/modules/UseInkscape.cmake
+++ b/cmake/modules/UseInkscape.cmake
@@ -1,12 +1,29 @@
# Module that provides convertion routines using inkscape
#
-# Provides the following functions:
+# .. cmake_function:: inkscape_generate_png_from_svg
#
-# inkscape_generate_png_from_svg([OUTPUT_DIR <output_dir>] <pngfile1.png> [<pngfile2.png> ....])
+# .. cmake_param:: OUTPUT_DIR
+# :single:
+#
+# The output directory for the generated png files.
+# Defaults to the current build directory.
+#
+# .. cmake_param:: pngfiles
+# :single:
+# :positional:
+# :required:
+#
+# The files that should be converted.
+#
+# .. cmake_param:: DPI
+# :single:
+#
+# dpi value for the generated image (default: 90)
+#
+# .. todo::
+#
+# Switch to named arguments!
#
-# Generates pngfile1, ... from svg input files pngfile1.svg, ....
-# The output directory can be specified with the option OUTPUT_DIR. If it is omitted
-# the files will be generated in CMAKE_CURRENT_BINARY_DIR.
include(CMakeParseArguments)
diff --git a/cmake/scripts/CMakeLists.txt b/cmake/scripts/CMakeLists.txt
index 9c2a5c8c9d017b831b0844522fe3e57c90d170fc..ee36fc83b9089ce8a80c2454c27e1c266e3f5866 100644
--- a/cmake/scripts/CMakeLists.txt
+++ b/cmake/scripts/CMakeLists.txt
@@ -1,9 +1,11 @@
set(modules
CreateDoxyFile.cmake
+ extract_cmake_data.py
FinalizeHeadercheck.cmake
FindFiles.cmake
InstallFile.cmake
- RunDoxygen.cmake)
+ RunDoxygen.cmake
+ sphinx_cmake_dune.py)
install(FILES ${modules} ${CMAKE_CURRENT_SOURCE_DIR}/BuildTests.cmake.in
DESTINATION ${CMAKE_INSTALL_DATAROOTDIR}/dune/cmake/scripts)
diff --git a/cmake/scripts/conf.py.in b/cmake/scripts/conf.py.in
new file mode 100644
index 0000000000000000000000000000000000000000..81a7da8f3838adc498673772031bf81657177e39
--- /dev/null
+++ b/cmake/scripts/conf.py.in
@@ -0,0 +1,5 @@
+import sys
+
+sys.path.append('@DUNE_SPHINX_EXT_PATH@')
+
+extensions = ['sphinx_cmake_dune']
diff --git a/cmake/scripts/extract_cmake_data.py b/cmake/scripts/extract_cmake_data.py
new file mode 100755
index 0000000000000000000000000000000000000000..5e53990ab8d677537fa5867d5b78b15093709730
--- /dev/null
+++ b/cmake/scripts/extract_cmake_data.py
@@ -0,0 +1,95 @@
+#!/usr/bin/env python
+
+""" This script will parse a cmake module and extract some
+ rst documentation from it. This might not be as elegant as
+ writing a Sphinx domain or using a custom extension with
+ cmake related directives, but it provides a straightforward
+ working way.
+
+ This is used by dune-common to generate the build system documentation.
+ Users do not want to use this!!!
+"""
+
+import argparse
+import os
+import re
+
+def get_args():
+ parser = argparse.ArgumentParser()
+ parser.add_argument('-b', '--builddir', help='The directory where to place the produced output', required=True)
+ parser.add_argument('-m', '--module', help='The module to parse', required=True)
+ return vars(parser.parse_args())
+
+def write_line(f, line):
+ if len(line) > 2:
+ f.write(line[2:])
+ else:
+ f.write('\n')
+
+def read_module(args=get_args()):
+ modname = os.path.splitext(os.path.basename(args['module']))[0]
+ modpath = os.path.join(args['builddir'], 'modules')
+ if not os.path.exists(modpath):
+ os.makedirs(modpath)
+ modfile = os.path.join(modpath, modname + '.rst')
+ with open(args['module'], 'r') as i:
+# mod = open(modfile, 'w')
+# # Write the first block into the module rst file
+# mod.write(".. _" + modname + ":\n\n")
+# mod.write(modname + "\n")
+# mod.write("="*len(modname) + "\n\n")
+
+# listHeader = False
+ o = None
+
+ for l in i:
+ if not l.startswith('#'):
+ return
+ if l.startswith('# .. cmake_function'):
+ if o:
+ o.close()
+ cmdpath = os.path.join(args['builddir'], 'commands')
+ if not os.path.exists(cmdpath):
+ os.makedirs(cmdpath)
+ cmd = re.findall(r'# .. cmake_function:: (.*)', l)[0]
+ cmdfile = os.path.join(cmdpath, cmd + ".rst")
+# if not listHeader:
+# mod.write("\nThis module defines the following functions or macros:\n\n")
+# listHeader = True
+# mod.write("* :ref:`{}`\n".format(cmd))
+ o = open(cmdfile, 'w')
+ o.write(".. _" + cmd + ":\n\n")
+ o.write(cmd + "\n")
+ o.write("="*len(cmd) + "\n\n")
+ write_line(o, l)
+ elif l.startswith('# .. cmake_variable'):
+ if o:
+ o.close()
+ varpath = os.path.join(args['builddir'], 'variables')
+ if not os.path.exists(varpath):
+ os.makedirs(varpath)
+ var = re.findall(r'# .. cmake_variable:: (.*)', l)[0]
+ varfile = os.path.join(varpath, var + ".rst")
+ o = open(varfile, 'w')
+ o.write(".. _" + var + ":\n\n")
+ o.write(var + "\n")
+ o.write("="*len(var) + "\n\n")
+ write_line(o, l)
+ elif l.startswith('# .. cmake_module'):
+ if o:
+ o.close()
+ modpath = os.path.join(args['builddir'], 'modules')
+ if not os.path.exists(modpath):
+ os.makedirs(modpath)
+ modfile = os.path.join(modpath, modname + ".rst")
+ o = open(modfile, 'w')
+ o.write(".. _" + modname + ":\n\n")
+ o.write(modname + "\n")
+ o.write("="*len(modname) + "\n\n")
+ write_line(o, l)
+ else:
+ if o:
+ write_line(o, l)
+
+# Parse the given arguments
+read_module()
diff --git a/cmake/scripts/sphinx_cmake_dune.py b/cmake/scripts/sphinx_cmake_dune.py
new file mode 100644
index 0000000000000000000000000000000000000000..ea8d8b0f8db964a0cad0c686032e586725585cb4
--- /dev/null
+++ b/cmake/scripts/sphinx_cmake_dune.py
@@ -0,0 +1,170 @@
+""" A cmake extension for Sphinx
+
+tailored for the Dune project.
+This is used during `make doc` to build the
+build system documentation.
+"""
+
+from docutils import nodes
+from docutils.parsers.rst import Directive
+from itertools import chain
+
+class CMakeParamNode(nodes.Element):
+ pass
+
+class CMakeBriefNode(nodes.Element):
+ pass
+
+class CMakeFunction(Directive):
+ # We do require the name to be an argument
+ required_arguments = 1
+ optional_arguments = 0
+ final_argument_whitespace = False
+ has_content = True
+
+ def run(self):
+ env = self.state.document.settings.env
+
+ # Parse the content of the directive recursively
+ node = nodes.Element()
+ node.document = self.state.document
+ self.state.nested_parse(self.content, self.content_offset, node)
+
+ brief_nodes = []
+ output_nodes = []
+ required_params = {}
+ optional_params = {}
+
+ for child in node:
+ if isinstance(child, CMakeParamNode):
+ if child["required"]:
+ required_params[child["name"]] = child
+ else:
+ optional_params[child["name"]] = child
+ elif isinstance(child, CMakeBriefNode):
+ par = nodes.paragraph()
+ self.state.nested_parse(child['content'], self.content_offset, par)
+ brief_nodes.append(par)
+ else:
+ output_nodes.append(child)
+
+ # Build the content of the box
+ sl = [self.arguments[0] + '(\n']
+ for rp, paramnode in required_params.items():
+ if paramnode["multi"]:
+ sl.append(" "*(len(self.arguments[0])+2) + paramnode['name'] + ' ' + paramnode['argname'] + '1 [' + paramnode['argname'] + '2 ...]\n')
+ if paramnode["single"]:
+ sl.append(" "*(len(self.arguments[0])+2) + paramnode['name'] + ' ' + paramnode['argname'] + '\n')
+ if paramnode["option"]:
+ sl.append(" "*(len(self.arguments[0])+2) + paramnode['name'] + '\n')
+
+ for op, paramnode in optional_params.items():
+ if paramnode["multi"]:
+ sl.append(' '*(len(self.arguments[0])+1) + '[' + paramnode['name'] + ' ' + paramnode['argname'] + '1 [' + paramnode['argname'] + '2 ...]' + ']\n')
+ if paramnode["single"]:
+ sl.append(" "*(len(self.arguments[0])+1) + '['+ paramnode['name'] + ' ' + paramnode['argname'] + ']\n')
+ if paramnode["option"]:
+ sl.append(" "*(len(self.arguments[0])+1) + '['+ paramnode['name'] + ']\n')
+
+ sl.append(")\n")
+ lb = nodes.literal_block(''.join(sl), ''.join(sl))
+ brief_nodes.append(lb)
+
+ dl = nodes.definition_list()
+ for param, paramnode in chain(required_params.items(), optional_params.items()):
+ dli = nodes.definition_list_item()
+ dl += dli
+
+ dlit = nodes.term(text=param)
+ dli += dlit
+
+ dlic = nodes.definition()
+ dli += dlic
+ self.state.nested_parse(paramnode['content'], self.content_offset, dlic)
+
+ # add the parameter list to the output
+ brief_nodes.append(dl)
+
+ return brief_nodes + output_nodes
+
+class CMakeBrief(Directive):
+ required_arguments = 0
+ optional_arguments = 0
+ final_argument_whitespace = False
+ has_content = True
+
+ def run(self):
+ node = CMakeBriefNode()
+ node['content'] = self.content
+ return [node]
+
+class CMakeParam(Directive):
+ # We do require the name to be an argument
+ required_arguments = 1
+ optional_arguments = 0
+ final_argument_whitespace = False
+ option_spec = {'argname' : lambda s: s,
+ 'multi': lambda s: True,
+ 'option': lambda s: True,
+ 'positional' : lambda s: True,
+ 'required': lambda s: True,
+ 'single': lambda s: True
+ }
+ has_content = True
+
+ def run(self):
+ node = CMakeParamNode()
+ # set defaults:
+ node['name'] = self.arguments[0]
+ node['single'] = self.options.get('single', False)
+ node['multi'] = self.options.get('multi', False)
+ node['option'] = self.options.get('option', False)
+ node['positional'] = self.options.get('positional', False)
+ node['required'] = self.options.get('required', False)
+ node['argname'] = self.options.get('argname', self.arguments[0].lower() if self.arguments[0].lower()[-1:] != 's' else self.arguments[0].lower()[:-1])
+ node['content'] = self.content
+ if node['positional']:
+ node['argname'] = ''
+ return [node]
+
+
+class CMakeVariable(Directive):
+ # We do require the name to be an argument
+ required_arguments = 1
+ optional_arguments = 0
+ final_argument_whitespace = False
+ option_spec = {'argname' : lambda s: s,
+ 'multi': lambda s: True,
+ 'option': lambda s: True,
+ 'positional' : lambda s: True,
+ 'required': lambda s: True,
+ 'single': lambda s: True
+ }
+ has_content = True
+
+ def run(self):
+ node = nodes.paragraph()
+ self.state.nested_parse(self.content, self.content_offset, node)
+ return [node]
+
+class CMakeModule(Directive):
+ required_arguments = 0
+ optional_arguments = 0
+ final_argument_whitespace = False
+ has_content = True
+
+ def run(self):
+ node = nodes.paragraph()
+ self.state.nested_parse(self.content, self.content_offset, node)
+ return [node]
+
+def setup(app):
+ app.add_node(CMakeBriefNode)
+ app.add_node(CMakeParamNode)
+ app.add_directive('cmake_module', CMakeModule)
+ app.add_directive('cmake_brief', CMakeBrief)
+ app.add_directive('cmake_function', CMakeFunction)
+ app.add_directive('cmake_param', CMakeParam)
+ app.add_directive('cmake_variable', CMakeVariable)
+
+ return {'version': '0.1'}
diff --git a/doc/buildsystem/CMakeLists.txt b/doc/buildsystem/CMakeLists.txt
index af4149cbbd75f9a7f1e7b64d0d16d3042ff91c56..1a848c26e149e997c1c4bbc041554e4378c5d597 100644
--- a/doc/buildsystem/CMakeLists.txt
+++ b/doc/buildsystem/CMakeLists.txt
@@ -1,5 +1,7 @@
-dune_add_latex_document(buildsystem.tex FATHER_TARGET doc DEFAULT_PDF INPUTS ../Makefile.am ../../configure.ac ../example.opts)
-create_doc_install(${CMAKE_CURRENT_BINARY_DIR}/buildsystem.pdf ${CMAKE_INSTALL_DOCDIR}/buildsystem)
+#dune_add_latex_document(buildsystem.tex FATHER_TARGET doc DEFAULT_PDF INPUTS ../Makefile.am ../../configure.ac ../example.opts)
+#create_doc_install(${CMAKE_CURRENT_BINARY_DIR}/buildsystem.pdf ${CMAKE_INSTALL_DOCDIR}/buildsystem)
+#
+#dune_add_latex_document(cmakefaq.tex FATHER_TARGET doc DEFAULT_PDF)
+#create_doc_install(${CMAKE_CURRENT_BINARY_DIR}/cmakefaq.pdf ${CMAKE_INSTALL_DOCDIR}/buildsystem)
-dune_add_latex_document(cmakefaq.tex FATHER_TARGET doc DEFAULT_PDF)
-create_doc_install(${CMAKE_CURRENT_BINARY_DIR}/cmakefaq.pdf ${CMAKE_INSTALL_DOCDIR}/buildsystem)
+dune_cmake_sphinx_doc(PATHS ${CMAKE_SOURCE_DIR}/cmake/modules)
diff --git a/doc/buildsystem/contents.rst b/doc/buildsystem/contents.rst
new file mode 100644
index 0000000000000000000000000000000000000000..e69de29bb2d1d6434b8b29ae775ad8c2e48c5391
diff --git a/doc/buildsystem/index.rst b/doc/buildsystem/index.rst
new file mode 100644
index 0000000000000000000000000000000000000000..ab05bb21a1175846c2c817b9bcba2e1d6a7684de
--- /dev/null
+++ b/doc/buildsystem/index.rst
@@ -0,0 +1,35 @@
+.. title:: dune-python CMake reference
+
+.. role:: cmake(code)
+ :language: cmake
+
+Introduction
+============
+.. toctree::
+ :maxdepth: 1
+
+ intro
+
+Input Variable reference
+==================
+.. toctree::
+ :maxdepth: 1
+ :glob:
+
+ variables/*
+
+Command reference
+=================
+.. toctree::
+ :maxdepth: 1
+ :glob:
+
+ commands/*
+
+Module reference
+================
+.. toctree::
+ :maxdepth: 1
+ :glob:
+
+ modules/*