[SuiteSparse] Add Sphinx documentation for *SuiteSparse*.cmake

cmake/modules/AddSuiteSparseFlags.cmake

-# module providing convenience methods for compiling
-# binaries with SuiteSparse support
+# Defines the functions to use SuiteSparse
 #
-# Provides the following functions:
+# .. cmake_function:: add_dune_suitesparse_flags
 #
-# add_dune_suitsparse_flags(target1 target2...)
+#    .. cmake_param:: targets
+#       :positional:
+#       :single:
+#       :required:
 #
-# adds SuiteSparse flags to the targets for compilation and linking
+#       A list of targets to use SuiteSparse with.
+#
+
 function(add_dune_suitesparse_flags _targets)
   if(SUITESPARSE_FOUND)
     foreach(_target ${_targets})

cmake/modules/FindSuiteSparse.cmake

-# Module that checks whether SuiteSparse is available.
+# .. cmake_module::
 #
-# Synopsis:
-#   find_package(SuiteSparse COMPONENTS component1 [component2 ...])
+#    Find the SuiteSparse libraries like UMFPACK or SPQR.
 #
-#  Components are:
-#   amd, btf, camd, ccolamd, cholmod, colamd, cxsparse,
-#   klu, ldl, RBio, spqr, umfpack
+#    .. cmake_param:: COMPONENTS
+#       :multi:
+#       :argname: component
 #
-# Variables used by this module which you may want to set:
-# SUITESPARSE_ROOT   Path list to search for SuiteSparse
+#       A list of required components. Components are:
+#       AMD, BTF, CAMD, CCOLAMD, CHOLMOD, COLAMD, CXSPARSE,
+#       KLU, LDL, RBIO, SPQR, UMFPACK
 #
-# Sets the following result variables:
+#    :ref:`SuiteSparse_ROOT`
+#       Path list to search for SuiteSparse
+#
+#    Sets the following variables:
+#
+#    :code:`SuiteSparse_FOUND`
+#       True if SuiteSparse was found.
+#
+#    :code:`SuiteSparse_INCLUDE_DIRS`
+#       Path to the SuiteSparse include dirs.
+#
+#    :code:`SuiteSparse_LIBRARIES`
+#       Name of the SuiteSparse libraries.
+#
+#    :code:`SuiteSparse_<COMPONENT>_FOUND`
+#       Whether <COMPONENT> was found as part of SuiteSparse.
+#
+# .. cmake_variable:: SuiteSparse_ROOT
+#
+#   You may set this variable to have :ref:`FindSuiteSparse` look
+#   for SuiteSparse in the given path before inspecting
+#   system paths.
 #
-# SuiteSparse_FOUND               Whether SuiteSparse was found and usable in the desired setting
-# SUITESPARSE_INCLUDE_DIRS        Path to the SuiteSparse include dirs
-# SUITESPARSE_LIBRARIES           Name of the SuiteSparse libraries
-# SUITESPARSE_<COMPONENT>_FOUND   Whether <COMPONENT> was found as part of SuiteSparse
 
 find_package(BLAS QUIET REQUIRED)
 if(NOT BLAS_FOUND)