FindPython{Interp,Libs}: Update documentation

Even though these modules are removed with a policy, documentation can
still be improved a bit to help when upgrading CMake code.

Changes:
- Synced modules documentation with other similar find modules.
- Added examples section to hint how to rewrite code using the
  FindPython module.
- FindPythonLibs:
  - Deprecated variables moved to a separate section.
  - PythonLibs_FOUND variable used. The PYTHONLIBS_FOUND variable is
    also set to the same value since CMake 3.3.
- FindPythonInterp:
  - PythonInterp_FOUND variable used. The PYTHONINTERP_FOUND variable is
    also set to the same value since CMake 3.3.

Modules/FindPythonInterp.cmake

@@ -10,47 +10,80 @@ FindPythonInterp
 
 .. deprecated:: 3.12
 
-  Use :module:`FindPython3`, :module:`FindPython2` or :module:`FindPython` instead.
+  Use :module:`FindPython3`, :module:`FindPython2`, or :module:`FindPython`
+  instead.
+
+This module finds the Python interpreter and determines the location of its
+executable.
 
-Find python interpreter
+.. note::
 
-This module finds if Python interpreter is installed and determines
-where the executables are.  This code sets the following variables:
+  When using both this and the :module:`FindPythonLibs` module, call
+  ``find_package(PythonInterp)`` before ``find_package(PythonLibs)``.  This
+  ensures that the detected interpreter version is used to guide the selection
+  of compatible libraries, resulting in a consistent ``PYTHON_LIBRARIES`` value.
 
-::
+.. note::
 
-  PYTHONINTERP_FOUND         - Was the Python executable found
-  PYTHON_EXECUTABLE          - path to the Python interpreter
+  A call to ``find_package(PythonInterp ${V})`` for Python version ``V`` may
+  find a ``python`` executable with no version suffix.  In this case no attempt
+  is made to avoid Python executables from other versions.  Use
+  :module:`FindPython3`, :module:`FindPython2`, or :module:`FindPython` instead.
 
+Result Variables
+^^^^^^^^^^^^^^^^
 
+This module defines the following variables:
 
-::
+``PythonInterp_FOUND``
+  Boolean indicating whether the (requested version of) Python executable is
+  found.  For backward compatibility, the ``PYTHONINTERP_FOUND`` variable is
+  also set to the same value.
+``PYTHON_VERSION_STRING``
+  Python version found (e.g., ``2.5.2``).
+``PYTHON_VERSION_MAJOR``
+  Python major version found (e.g., ``2``).
+``PYTHON_VERSION_MINOR``
+  Python minor version found (e.g., ``5``).
+``PYTHON_VERSION_PATCH``
+  Python patch version found (e.g., ``2``).
 
-  PYTHON_VERSION_STRING      - Python version found e.g. 2.5.2
-  PYTHON_VERSION_MAJOR       - Python major version found e.g. 2
-  PYTHON_VERSION_MINOR       - Python minor version found e.g. 5
-  PYTHON_VERSION_PATCH       - Python patch version found e.g. 2
+Cache Variables
+^^^^^^^^^^^^^^^
 
+The following cache variables may also be set:
 
+``PYTHON_EXECUTABLE``
+  The path to the Python interpreter.
 
-The Python_ADDITIONAL_VERSIONS variable can be used to specify a list
-of version numbers that should be taken into account when searching
-for Python.  You need to set this variable before calling
-find_package(PythonInterp).
+Hints
+^^^^^
 
-If calling both ``find_package(PythonInterp)`` and
-``find_package(PythonLibs)``, call ``find_package(PythonInterp)`` first to
-get the currently active Python version by default with a consistent version
-of PYTHON_LIBRARIES.
+This module accepts the following variables before calling
+``find_package(PythonInterp)``:
 
-.. note::
+``Python_ADDITIONAL_VERSIONS``
+  This variable can be used to specify a list of version numbers that should be
+  taken into account when searching for Python.
 
-  A call to ``find_package(PythonInterp ${V})`` for python version ``V``
-  may find a ``python`` executable with no version suffix.  In this case
-  no attempt is made to avoid python executables from other versions.
-  Use :module:`FindPython3`, :module:`FindPython2` or :module:`FindPython`
-  instead.
+Examples
+^^^^^^^^
+
+Finding the Python interpreter in earlier versions of CMake:
+
+.. code-block:: cmake
+
+  find_package(PythonInterp)
+  execute_process(COMMAND ${PYTHON_EXECUTABLE} --help)
+
+Starting with CMake 3.12, the Python interpreter can be found using the
+:module:`FindPython` module.  The equivalent example using the modern approach
+is:
+
+.. code-block:: cmake
 
+  find_package(Python)
+  execute_process(COMMAND ${Python_EXECUTABLE} --help)
 #]=======================================================================]
 
 cmake_policy(GET CMP0148 _FindPythonInterp_CMP0148)

Modules/FindPythonLibs.cmake

@@ -10,42 +10,101 @@ FindPythonLibs
 
 .. deprecated:: 3.12
 
-  Use :module:`FindPython3`, :module:`FindPython2` or :module:`FindPython` instead.
+  Use :module:`FindPython3`, :module:`FindPython2`, or :module:`FindPython`
+  instead.
 
-Find python libraries
+This module finds the Python installation and determines the location of its
+include directories and libraries, as well as the name of the Python library to
+link against.
 
-This module finds if Python is installed and determines where the
-include files and libraries are.  It also determines what the name of
-the library is.  This code sets the following variables:
+.. note::
 
-::
+  When using both this and the :module:`FindPythonInterp` module, call
+  ``find_package(PythonInterp)`` before ``find_package(PythonLibs)``.  This
+  ensures that the detected interpreter version is used to guide the selection
+  of compatible libraries, resulting in a consistent ``PYTHON_LIBRARIES`` value.
 
-  PYTHONLIBS_FOUND           - have the Python libs been found
-  PYTHON_LIBRARIES           - path to the python library
-  PYTHON_INCLUDE_PATH        - path to where Python.h is found (deprecated)
-  PYTHON_INCLUDE_DIRS        - path to where Python.h is found
-  PYTHON_DEBUG_LIBRARIES     - path to the debug library (deprecated)
-  PYTHONLIBS_VERSION_STRING  - version of the Python libs found (since CMake 2.8.8)
+Result Variables
+^^^^^^^^^^^^^^^^
 
+This module defines the following variables:
 
+``PythonLibs_FOUND``
+  Boolean indicating whether the (requested version of) Python libraries have
+  been found.  For backward compatibility, the ``PYTHONLIBS_FOUND`` variable is
+  also set to the same value.
 
-The Python_ADDITIONAL_VERSIONS variable can be used to specify a list
-of version numbers that should be taken into account when searching
-for Python.  You need to set this variable before calling
-find_package(PythonLibs).
+``PYTHONLIBS_VERSION_STRING``
+  .. versionadded:: 2.8.8
 
-If you'd like to specify the installation of Python to use, you should
-modify the following cache variables:
+  The version of the Python libraries found.
 
-::
+``PYTHON_LIBRARIES``
+  Libraries needed to link against to use Python.
 
-  PYTHON_LIBRARY             - path to the python library
-  PYTHON_INCLUDE_DIR         - path to where Python.h is found
+``PYTHON_INCLUDE_DIRS``
+  Include directories needed to use Python.
 
-If calling both ``find_package(PythonInterp)`` and
-``find_package(PythonLibs)``, call ``find_package(PythonInterp)`` first to
-get the currently active Python version by default with a consistent version
-of PYTHON_LIBRARIES.
+Cache Variables
+^^^^^^^^^^^^^^^
+
+The following cache variables may also be set to specify the Python installation
+to use:
+
+``PYTHON_LIBRARY``
+  The path to the Python library.
+
+``PYTHON_INCLUDE_DIR``
+  The directory containing the ``Python.h`` header file.
+
+Hints
+^^^^^
+
+This module accepts the following variables before calling
+``find_package(PythonLibs)``:
+
+``Python_ADDITIONAL_VERSIONS``
+  This variable can be used to specify a list of version numbers that should be
+  taken into account when searching for Python.
+
+Deprecated Variables
+^^^^^^^^^^^^^^^^^^^^
+
+These variables are provided for backward compatibility:
+
+``PYTHON_DEBUG_LIBRARIES``
+  .. deprecated:: 2.8.8
+    Use ``PYTHON_LIBRARIES`` instead.
+
+  Result variable that holds the path to the debug library.
+
+``PYTHON_INCLUDE_PATH``
+  .. deprecated:: 2.8.0
+    Use ``PYTHON_INCLUDE_DIR`` or ``PYTHON_INCLUDE_DIRS`` instead.
+
+  Result variable that holds the path to the directory containing the
+  ``Python.h`` header file.
+
+Examples
+^^^^^^^^
+
+In earlier versions of CMake, Python libraries were found and used in a project
+like this:
+
+.. code-block:: cmake
+
+  find_package(PythonLibs)
+  target_link_libraries(app PRIVATE ${PYTHON_LIBRARIES})
+  target_include_directories(app PRIVATE ${PYTHON_INCLUDE_DIRS})
+
+Starting with CMake 3.12, Python libraries can be found using the
+:module:`FindPython` module.  The equivalent example using the modern approach
+with an imported target is:
+
+.. code-block:: cmake
+
+  find_package(Python COMPONENTS Development)
+  target_link_libraries(app PRIVATE Python::Python)
 #]=======================================================================]
 
 cmake_policy(PUSH)