Convert builtin help to reStructuredText source files

Run the convert-help.bash script to convert documentation:

 ./convert-help.bash "/path/to/CMake-build/bin"

Then remove it.

1 files changed, 71 insertions, 47 deletions

diff --git a/Modules/FindMPI.cmake b/Modules/FindMPI.cmake
index 0eb86a80a0..c8d46ba9db 100644
--- a/Modules/FindMPI.cmake
+++ b/Modules/FindMPI.cmake
@@ -1,64 +1,88 @@
-# - Find a Message Passing Interface (MPI) implementation
+#.rst:
+# FindMPI
+# -------
+#
+# Find a Message Passing Interface (MPI) implementation
+#
 # The Message Passing Interface (MPI) is a library used to write
-# high-performance distributed-memory parallel applications, and
-# is typically deployed on a cluster. MPI is a standard interface
-# (defined by the MPI forum) for which many implementations are
-# available. All of them have somewhat different include paths,
-# libraries to link against, etc., and this module tries to smooth
-# out those differences.
+# high-performance distributed-memory parallel applications, and is
+# typically deployed on a cluster.  MPI is a standard interface (defined
+# by the MPI forum) for which many implementations are available.  All
+# of them have somewhat different include paths, libraries to link
+# against, etc., and this module tries to smooth out those differences.
 #
 # === Variables ===
 #
-# This module will set the following variables per language in your project,
-# where <lang> is one of C, CXX, or Fortran:
-#   MPI_<lang>_FOUND           TRUE if FindMPI found MPI flags for <lang>
-#   MPI_<lang>_COMPILER        MPI Compiler wrapper for <lang>
-#   MPI_<lang>_COMPILE_FLAGS   Compilation flags for MPI programs
-#   MPI_<lang>_INCLUDE_PATH    Include path(s) for MPI header
-#   MPI_<lang>_LINK_FLAGS      Linking flags for MPI programs
-#   MPI_<lang>_LIBRARIES       All libraries to link MPI programs against
+# This module will set the following variables per language in your
+# project, where <lang> is one of C, CXX, or Fortran:
+#
+# ::
+#
+#    MPI_<lang>_FOUND           TRUE if FindMPI found MPI flags for <lang>
+#    MPI_<lang>_COMPILER        MPI Compiler wrapper for <lang>
+#    MPI_<lang>_COMPILE_FLAGS   Compilation flags for MPI programs
+#    MPI_<lang>_INCLUDE_PATH    Include path(s) for MPI header
+#    MPI_<lang>_LINK_FLAGS      Linking flags for MPI programs
+#    MPI_<lang>_LIBRARIES       All libraries to link MPI programs against
+#
 # Additionally, FindMPI sets the following variables for running MPI
 # programs from the command line:
-#   MPIEXEC                    Executable for running MPI programs
-#   MPIEXEC_NUMPROC_FLAG       Flag to pass to MPIEXEC before giving
-#                              it the number of processors to run on
-#   MPIEXEC_PREFLAGS           Flags to pass to MPIEXEC directly
-#                              before the executable to run.
-#   MPIEXEC_POSTFLAGS          Flags to pass to MPIEXEC after other flags
+#
+# ::
+#
+#    MPIEXEC                    Executable for running MPI programs
+#    MPIEXEC_NUMPROC_FLAG       Flag to pass to MPIEXEC before giving
+#                               it the number of processors to run on
+#    MPIEXEC_PREFLAGS           Flags to pass to MPIEXEC directly
+#                               before the executable to run.
+#    MPIEXEC_POSTFLAGS          Flags to pass to MPIEXEC after other flags
+#
 # === Usage ===
 #
 # To use this module, simply call FindMPI from a CMakeLists.txt file, or
-# run find_package(MPI), then run CMake.  If you are happy with the auto-
-# detected configuration for your language, then you're done.  If not, you
-# have two options:
-#   1. Set MPI_<lang>_COMPILER to the MPI wrapper (mpicc, etc.) of your
-#      choice and reconfigure.  FindMPI will attempt to determine all the
-#      necessary variables using THAT compiler's compile and link flags.
-#   2. If this fails, or if your MPI implementation does not come with
-#      a compiler wrapper, then set both MPI_<lang>_LIBRARIES and
-#      MPI_<lang>_INCLUDE_PATH.  You may also set any other variables
-#      listed above, but these two are required.  This will circumvent
-#      autodetection entirely.
-# When configuration is successful, MPI_<lang>_COMPILER will be set to the
-# compiler wrapper for <lang>, if it was found.  MPI_<lang>_FOUND and other
-# variables above will be set if any MPI implementation was found for <lang>,
-# regardless of whether a compiler was found.
-#
-# When using MPIEXEC to execute MPI applications, you should typically use
-# all of the MPIEXEC flags as follows:
-#   ${MPIEXEC} ${MPIEXEC_NUMPROC_FLAG} PROCS
-#     ${MPIEXEC_PREFLAGS} EXECUTABLE ${MPIEXEC_POSTFLAGS} ARGS
-# where PROCS is the number of processors on which to execute the program,
-# EXECUTABLE is the MPI program, and ARGS are the arguments to pass to the
-# MPI program.
+# run find_package(MPI), then run CMake.  If you are happy with the
+# auto- detected configuration for your language, then you're done.  If
+# not, you have two options:
+#
+# ::
+#
+#    1. Set MPI_<lang>_COMPILER to the MPI wrapper (mpicc, etc.) of your
+#       choice and reconfigure.  FindMPI will attempt to determine all the
+#       necessary variables using THAT compiler's compile and link flags.
+#    2. If this fails, or if your MPI implementation does not come with
+#       a compiler wrapper, then set both MPI_<lang>_LIBRARIES and
+#       MPI_<lang>_INCLUDE_PATH.  You may also set any other variables
+#       listed above, but these two are required.  This will circumvent
+#       autodetection entirely.
+#
+# When configuration is successful, MPI_<lang>_COMPILER will be set to
+# the compiler wrapper for <lang>, if it was found.  MPI_<lang>_FOUND
+# and other variables above will be set if any MPI implementation was
+# found for <lang>, regardless of whether a compiler was found.
+#
+# When using MPIEXEC to execute MPI applications, you should typically
+# use all of the MPIEXEC flags as follows:
+#
+# ::
+#
+#    ${MPIEXEC} ${MPIEXEC_NUMPROC_FLAG} PROCS
+#      ${MPIEXEC_PREFLAGS} EXECUTABLE ${MPIEXEC_POSTFLAGS} ARGS
+#
+# where PROCS is the number of processors on which to execute the
+# program, EXECUTABLE is the MPI program, and ARGS are the arguments to
+# pass to the MPI program.
 #
 # === Backward Compatibility ===
 #
 # For backward compatibility with older versions of FindMPI, these
 # variables are set, but deprecated:
-#   MPI_FOUND           MPI_COMPILER        MPI_LIBRARY
-#   MPI_COMPILE_FLAGS   MPI_INCLUDE_PATH    MPI_EXTRA_LIBRARY
-#   MPI_LINK_FLAGS      MPI_LIBRARIES
+#
+# ::
+#
+#    MPI_FOUND           MPI_COMPILER        MPI_LIBRARY
+#    MPI_COMPILE_FLAGS   MPI_INCLUDE_PATH    MPI_EXTRA_LIBRARY
+#    MPI_LINK_FLAGS      MPI_LIBRARIES
+#
 # In new projects, please use the MPI_<lang>_XXX equivalents.
 
 #=============================================================================