extend module documentation

modules/build_info.cmake

@@ -1,5 +1,7 @@
-# Copyright (c) 2015 by Radovan Bast and Jonas Juselius
+#.rst:
-# see https://github.com/scisoft/autocmake/blob/master/LICENSE
+#
+# Generates source code that echoes configuration and build
+# information to the program output.
 
 # generated cmake files will be written to this path
 # only build info is generated

modules/code_coverage.cmake

@@ -1,3 +1,20 @@
+#.rst:
+#
+# Enables code coverage by appending corresponding compiler flags.
+#
+# Variables modified (provided the corresponding language is enabled)::
+#
+#   CMAKE_Fortran_FLAGS
+#   CMAKE_C_FLAGS
+#   CMAKE_CXX_FLAGS
+#
+# Example autocmake.cfg entry::
+#
+#   [coverage]
+#   source: https://github.com/scisoft/autocmake/raw/master/modules/code_coverage.cmake
+#   docopt: --coverage Enable code coverage [default: False].
+#   define: '-DENABLE_CODE_COVERAGE=%s' % arguments['--coverage']
+
 option(ENABLE_CODE_COVERAGE "Enable code coverage" OFF)
 
 if(ENABLE_CODE_COVERAGE)

modules/default_build_paths.cmake

@@ -1,2 +1,17 @@
+#.rst:
+#
+# Sets binary and library output directories to ${PROJECT_BINARY_DIR}/bin
+# and ${PROJECT_BINARY_DIR}/lib, respectively.
+#
+# Variables modified::
+#
+#   CMAKE_RUNTIME_OUTPUT_DIRECTORY
+#   CMAKE_LIBRARY_OUTPUT_DIRECTORY
+#
+# Example autocmake.cfg entry::
+#
+#   [default_build_paths]
+#   source: https://github.com/scisoft/autocmake/raw/master/modules/default_build_paths.cmake
+
 set(CMAKE_RUNTIME_OUTPUT_DIRECTORY ${PROJECT_BINARY_DIR}/bin)
 set(CMAKE_LIBRARY_OUTPUT_DIRECTORY ${PROJECT_BINARY_DIR}/lib)

modules/int64.cmake

@@ -1,3 +1,18 @@
+#.rst:
+#
+# Enables 64-bit integer support for Fortran projects.
+#
+# Variables modified (provided the corresponding language is enabled)::
+#
+#   CMAKE_Fortran_FLAGS
+#
+# Example autocmake.cfg entry::
+#
+#   [int64]
+#   source: https://github.com/scisoft/autocmake/raw/master/modules/int64.cmake
+#   docopt: --int64 Enable 64bit integers [default: False].
+#   define: '-DENABLE_64BIT_INTEGERS=%s' % arguments['--int64']
+
 option(ENABLE_64BIT_INTEGERS "Enable 64-bit integers" OFF)
 
 if(ENABLE_64BIT_INTEGERS)

modules/math_libs.cmake

@@ -1,33 +1,50 @@
-
+#.rst:
-# Copyright (c) 2015 by Radovan Bast and Jonas Juselius
+#
-# see https://github.com/scisoft/autocmake/blob/master/LICENSE
+# Detects and links to BLAS and LAPACK libraries.
-
+#
-# CMake variables used:
+# Variables used::
-#     - MATH_LIB_SEARCH_ORDER, example: set(MATH_LIB_SEARCH_ORDER MKL ESSL ATLAS ACML SYSTEM_NATIVE)
+#
-#     - ENABLE_BLAS
+#   MATH_LIB_SEARCH_ORDER, example: set(MATH_LIB_SEARCH_ORDER MKL ESSL ATLAS ACML SYSTEM_NATIVE)
-#     - ENABLE_LAPACK
+#   ENABLE_BLAS
-#     - BLAS_FOUND
+#   ENABLE_LAPACK
-#     - LAPACK_FOUND
+#   BLAS_FOUND
-#     - BLAS_LANG
+#   LAPACK_FOUND
-#     - LAPACK_LANG
+#   BLAS_LANG
-#     - BLAS_TYPE
+#   LAPACK_LANG
-#     - LAPACK_TYPE
+#   BLAS_TYPE
-#     - ENABLE_64BIT_INTEGERS
+#   LAPACK_TYPE
-#     - CMAKE_HOST_SYSTEM_PROCESSOR
+#   ENABLE_64BIT_INTEGERS
-#     - BLACS_IMPLEMENTATION
+#   CMAKE_HOST_SYSTEM_PROCESSOR
-#     - MKL_FLAG
+#   BLACS_IMPLEMENTATION
-
+#   MKL_FLAG
-# Environment variables used:
+#
-#     - MATH_ROOT
+# Variables set::
-#     - BLAS_ROOT
+#
-#     - LAPACK_ROOT
+#   MATH_LIBS
-#     - MKL_ROOT
+#   BLAS_FOUND
-#     - MKLROOT
+#   LAPACK_FOUND
-
+#
-# CMake variables set:
+# Environment variables used::
-#     - MATH_LIBS
+#
-#     - BLAS_FOUND
+#   MATH_ROOT
-#     - LAPACK_FOUND
+#   BLAS_ROOT
+#   LAPACK_ROOT
+#   MKL_ROOT
+#   MKLROOT
+#
+# Example autocmake.cfg entry::
+#
+#   [math_libs]
+#   source: https://github.com/scisoft/autocmake/raw/master/modules/math_libs.cmake
+#   docopt: --blas=<BLAS> Detect and link BLAS library (auto or off) [default: auto].
+#           --lapack=<LAPACK> Detect and link LAPACK library (auto or off) [default: auto].
+#           --mkl=<MKL> Pass MKL flag to the Intel compiler and linker and skip BLAS/LAPACK detection (sequential, parallel, cluster, or off) [default: off].
+#   define: '-DENABLE_BLAS=%s' % arguments['--blas']
+#           '-DENABLE_LAPACK=%s' % arguments['--lapack']
+#           '-DMKL_FLAG=%s' % arguments['--mkl']
+#           '-DMATH_LIB_SEARCH_ORDER="MKL;ESSL;ATLAS;ACML;SYSTEM_NATIVE"'
+#           '-DBLAS_LANG=Fortran'
+#           '-DLAPACK_LANG=Fortran'
 
 #-------------------------------------------------------------------------------
 # SYSTEM_NATIVE

modules/version.cmake

@@ -4,7 +4,7 @@
 # The reason why this information is stored
 # in a file and not as CMake variable is that CMake-unaware programs can parse
 # and use it (e.g. Sphinx). Also web-based hosting frontends such as GitLab
-# automatically use a file "VERSION".
+# automatically use the file "VERSION" if present.
 #
 # Variables defined::
 #