[SuiteSparse] Mark FindUMPFack as deprecated, update Sphinx documentation

cmake/modules/FindSuiteSparse.cmake

@@ -4,10 +4,10 @@
 #
 #    Example which tries to find Suite Sparse's UMFPack component:
 #
-#    :code:`find(SuiteSparse COMPONENTS UMFPACK)`
+#    :code:`find_package(SuiteSparse OPTIONAL_COMPONENTS UMFPACK)`
 #
-#    :ref:`COMPONENTS`
-#       A list of required components. Components are:
+#    `OPTIONAL_COMPONENTS`
+#       A list of components. Components are:
 #       AMD, BTF, CAMD, CCOLAMD, CHOLMOD, COLAMD, CXSPARSE,
 #       KLU, LDL, RBIO, SPQR, UMFPACK
 #

cmake/modules/FindUMFPack.cmake

@@ -2,6 +2,9 @@
 #
 #    Find the UMFPack library
 #
+# .. deprecated:: 3.0
+#    Use :code:`find_package(SuiteSparse OPTIONAL_COMPONENTS UMFPACK)` instead
+#
 #    You may set the following variables to modify the
 #    behaviour of this module:
 #
@@ -28,6 +31,9 @@
 
 find_package(SuiteSparse OPTIONAL_COMPONENTS UMFPACK)
 
+# use find_package(SuiteSparse OPTIONAL_COMPONENTS UMFPACK) instead
+message(WARNING "find_package(UMFPack) is deprecated, please use FindSuiteSparse instead")
+
 set(UMFPACK_INCLUDE_DIRS ${SuiteSparse_INCLUDE_DIRS})
 set(UMFPACK_LIBRARIES ${SuiteSparse_LIBRARIES})