Merge topic 'module-index-restructure'

dc372f6eef Help: Document Use_wxWindows.cmake as deprecated
846e3d2ceb Help: Reorganise module index into sections
c9cedd675b Help: Add link to cmake-qt(7) to FindQt.cmake.

Acked-by: Kitware Robot <[email protected]>
Merge-request: !2463

Help/manual/cmake-modules.7.rst

@@ -3,12 +3,14 @@
 cmake-modules(7)
 ****************
 
-.. only:: html
+The modules listed here are part of the CMake distribution.
+Projects may provide further modules; their location(s)
+can be specified in the :variable:`CMAKE_MODULE_PATH` variable.
 
-   .. contents::
+Utility Modules
+^^^^^^^^^^^^^^^
 
-All Modules
-===========
+These modules are loaded using the :command:`include` command.
 
 .. toctree::
    :maxdepth: 1
@@ -41,12 +43,9 @@ All Modules
    /module/CMakeAddFortranSubdirectory
    /module/CMakeBackwardCompatibilityCXX
    /module/CMakeDependentOption
-   /module/CMakeDetermineVSServicePack
-   /module/CMakeExpandImportedTargets
    /module/CMakeFindDependencyMacro
    /module/CMakeFindFrameworks
    /module/CMakeFindPackageMode
-   /module/CMakeForceCompiler
    /module/CMakeGraphVizOptions
    /module/CMakePackageConfigHelpers
    /module/CMakeParseArguments
@@ -70,6 +69,42 @@ All Modules
    /module/ExternalProject
    /module/FeatureSummary
    /module/FetchContent
+   /module/FindPackageHandleStandardArgs
+   /module/FindPackageMessage
+   /module/FortranCInterface
+   /module/GenerateExportHeader
+   /module/GetPrerequisites
+   /module/GNUInstallDirs
+   /module/GoogleTest
+   /module/InstallRequiredSystemLibraries
+   /module/MacroAddFileDependencies
+   /module/ProcessorCount
+   /module/SelectLibraryConfigurations
+   /module/SquishTestScript
+   /module/TestBigEndian
+   /module/TestForANSIForScope
+   /module/TestForANSIStreamHeaders
+   /module/TestForSSTREAM
+   /module/TestForSTDNamespace
+   /module/UseEcos
+   /module/UseJavaClassFilelist
+   /module/UseJava
+   /module/UseJavaSymlinks
+   /module/UsePkgConfig
+   /module/UseSWIG
+   /module/UsewxWidgets
+   /module/Use_wxWindows
+   /module/WriteCompilerDetectionHeader
+
+Find Modules
+^^^^^^^^^^^^
+
+These modules search for third-party software.
+They are normally called through the :command:`find_package` command.
+
+.. toctree::
+   :maxdepth: 1
+
    /module/FindALSA
    /module/FindArmadillo
    /module/FindASPELL
@@ -82,7 +117,6 @@ All Modules
    /module/FindBZip2
    /module/FindCABLE
    /module/FindCoin3D
-   /module/FindCUDA
    /module/FindCups
    /module/FindCURL
    /module/FindCurses
@@ -173,8 +207,6 @@ All Modules
    /module/FindosgViewer
    /module/FindosgVolume
    /module/FindosgWidget
-   /module/FindPackageHandleStandardArgs
-   /module/FindPackageMessage
    /module/FindPatch
    /module/FindPerlLibs
    /module/FindPerl
@@ -189,8 +221,6 @@ All Modules
    /module/FindPython
    /module/FindPython2
    /module/FindPython3
-   /module/FindPythonInterp
-   /module/FindPythonLibs
    /module/FindQt3
    /module/FindQt4
    /module/FindQt
@@ -218,39 +248,39 @@ All Modules
    /module/FindWget
    /module/FindWish
    /module/FindwxWidgets
-   /module/FindwxWindows
    /module/FindXCTest
    /module/FindXalanC
    /module/FindXercesC
    /module/FindX11
    /module/FindXMLRPC
    /module/FindZLIB
-   /module/FortranCInterface
-   /module/GenerateExportHeader
-   /module/GetPrerequisites
-   /module/GNUInstallDirs
-   /module/GoogleTest
-   /module/InstallRequiredSystemLibraries
-   /module/MacroAddFileDependencies
-   /module/ProcessorCount
-   /module/SelectLibraryConfigurations
-   /module/SquishTestScript
-   /module/TestBigEndian
+
+Deprecated Modules
+^^^^^^^^^^^^^^^^^^^
+
+Deprecated Utility Modules
+==========================
+
+.. toctree::
+   :maxdepth: 1
+
+   /module/CMakeDetermineVSServicePack
+   /module/CMakeExpandImportedTargets
+   /module/CMakeForceCompiler
    /module/TestCXXAcceptsFlag
-   /module/TestForANSIForScope
-   /module/TestForANSIStreamHeaders
-   /module/TestForSSTREAM
-   /module/TestForSTDNamespace
-   /module/UseEcos
-   /module/UseJavaClassFilelist
-   /module/UseJava
-   /module/UseJavaSymlinks
-   /module/UsePkgConfig
-   /module/UseSWIG
-   /module/UsewxWidgets
    /module/Use_wxWindows
    /module/WriteBasicConfigVersionFile
-   /module/WriteCompilerDetectionHeader
+
+Deprecated Find Modules
+=======================
+
+.. toctree::
+   :maxdepth: 1
+
+   /module/FindCUDA
+   /module/FindPythonInterp
+   /module/FindPythonLibs
+   /module/FindwxWindows
 
 Legacy CPack Modules
 ====================

Modules/FindQt.cmake

@@ -5,9 +5,12 @@
 # FindQt
 # ------
 #
-# Searches for all installed versions of Qt.
+# Searches for all installed versions of Qt3 or Qt4.
 #
-# This should only be used if your project can work with multiple
+# This module cannot handle Qt5 or any later versions.
+# For those, see :manual:`cmake-qt(7)`.
+#
+# This module should only be used if your project can work with multiple
 # versions of Qt.  If not, you should just directly use FindQt4 or
 # FindQt3.  If multiple versions of Qt are found on the machine, then
 # The user must set the option DESIRED_QT_VERSION to the version they
@@ -16,9 +19,6 @@
 # or FindQt4 module is included.  Once the user sets DESIRED_QT_VERSION,
 # then the FindQt3 or FindQt4 module is included.
 #
-# This module can only detect and switch between Qt versions 3 and 4. It
-# cannot handle Qt5 or any later versions.
-#
 # ::
 #
 #   QT_REQUIRED if this is set to TRUE then if CMake can

Modules/Use_wxWindows.cmake

@@ -5,7 +5,8 @@
 # Use_wxWindows
 # -------------
 #
-#
+# Deprecated.  Use ``find_package(wxWidgets)`` and
+# ``include(${wxWidgets_USE_FILE})`` instead.
 #
 #
 # This convenience include finds if wxWindows is installed and set the