ExternalProject: Use explicit markup and definition lists in docs

Convert ExternalProject module documentation to use explicit markup
blocks for each command.  Enumerate command options with definition
lists instead of a literal block.  This will allow more detail to be
added later.  Also fix the logic that parses options out of the
documentation to be aware of the new layout.

1 files changed, 227 insertions, 139 deletions

diff --git a/Modules/ExternalProject.cmake b/Modules/ExternalProject.cmake
index 54432e3f6e..a92f20c556 100644
--- a/Modules/ExternalProject.cmake
+++ b/Modules/ExternalProject.cmake
@@ -4,132 +4,216 @@ ExternalProject
 
 Create custom targets to build projects in external trees
 
-The ``ExternalProject_Add`` function creates a custom target to drive
-download, update/patch, configure, build, install and test steps of an
-external project:
-
-.. code-block:: cmake
-
- ExternalProject_Add(<name>    # Name for custom target
-   [DEPENDS projects...]       # Targets on which the project depends
-   [PREFIX dir]                # Root dir for entire project
-   [LIST_SEPARATOR sep]        # Sep to be replaced by ; in cmd lines
-   [TMP_DIR dir]               # Directory to store temporary files
-   [STAMP_DIR dir]             # Directory to store step timestamps
-   [EXCLUDE_FROM_ALL 1]        # The "all" target does not depend on this
-  #--Download step--------------
-   [DOWNLOAD_NAME fname]       # File name to store (if not end of URL)
-   [DOWNLOAD_DIR dir]          # Directory to store downloaded files
-   [DOWNLOAD_COMMAND cmd...]   # Command to download source tree
-   [DOWNLOAD_NO_PROGRESS 1]    # Disable download progress reports
-   [CVS_REPOSITORY cvsroot]    # CVSROOT of CVS repository
-   [CVS_MODULE mod]            # Module to checkout from CVS repo
-   [CVS_TAG tag]               # Tag to checkout from CVS repo
-   [SVN_REPOSITORY url]        # URL of Subversion repo
-   [SVN_REVISION -r<rev>]      # Revision to checkout from Subversion repo
-   [SVN_USERNAME john ]        # Username for Subversion checkout and update
-   [SVN_PASSWORD doe ]         # Password for Subversion checkout and update
-   [SVN_TRUST_CERT 1 ]         # Trust the Subversion server site certificate
-   [GIT_REPOSITORY url]        # URL of git repo
-   [GIT_TAG tag]               # Git branch name, commit id or tag
-   [GIT_SUBMODULES modules...] # Git submodules that shall be updated, all if empty
-   [HG_REPOSITORY url]         # URL of mercurial repo
-   [HG_TAG tag]                # Mercurial branch name, commit id or tag
-   [URL /.../src.tgz]          # Full path or URL of source
-   [URL_HASH ALGO=value]       # Hash of file at URL
-   [URL_MD5 md5]               # Equivalent to URL_HASH MD5=md5
-   [TLS_VERIFY bool]           # Should certificate for https be checked
-   [TLS_CAINFO file]           # Path to a certificate authority file
-   [TIMEOUT seconds]           # Time allowed for file download operations
-  #--Update/Patch step----------
-   [UPDATE_COMMAND cmd...]     # Source work-tree update command
-   [PATCH_COMMAND cmd...]      # Command to patch downloaded source
-  #--Configure step-------------
-   [SOURCE_DIR dir]            # Source dir to be used for build
-   [CONFIGURE_COMMAND cmd...]  # Build tree configuration command
-   [CMAKE_COMMAND /.../cmake]  # Specify alternative cmake executable
-   [CMAKE_GENERATOR gen]       # Specify generator for native build
-   [CMAKE_GENERATOR_PLATFORM p] # Generator-specific platform name
-   [CMAKE_GENERATOR_TOOLSET t] # Generator-specific toolset name
-   [CMAKE_ARGS args...]        # Arguments to CMake command line
-   [CMAKE_CACHE_ARGS args...]  # Initial cache arguments, of the form -Dvar:string=on
-  #--Build step-----------------
-   [BINARY_DIR dir]            # Specify build dir location
-   [BUILD_COMMAND cmd...]      # Command to drive the native build
-   [BUILD_IN_SOURCE 1]         # Use source dir for build dir
-   [BUILD_ALWAYS 1]            # No stamp file, build step always runs
-  #--Install step---------------
-   [INSTALL_DIR dir]           # Installation prefix
-   [INSTALL_COMMAND cmd...]    # Command to drive install after build
-  #--Test step------------------
-   [TEST_BEFORE_INSTALL 1]     # Add test step executed before install step
-   [TEST_AFTER_INSTALL 1]      # Add test step executed after install step
-   [TEST_COMMAND cmd...]       # Command to drive test
-  #--Output logging-------------
-   [LOG_DOWNLOAD 1]            # Wrap download in script to log output
-   [LOG_UPDATE 1]              # Wrap update in script to log output
-   [LOG_CONFIGURE 1]           # Wrap configure in script to log output
-   [LOG_BUILD 1]               # Wrap build in script to log output
-   [LOG_TEST 1]                # Wrap test in script to log output
-   [LOG_INSTALL 1]             # Wrap install in script to log output
-  #--Custom targets-------------
-   [STEP_TARGETS st1 st2 ...]  # Generate custom targets for these steps
-   )
-
-The ``*_DIR`` options specify directories for the project, with default
-directories computed as follows.  If the ``PREFIX`` option is given to
-``ExternalProject_Add()`` or the ``EP_PREFIX`` directory property is set,
-then an external project is built and installed under the specified prefix::
-
- TMP_DIR      = <prefix>/tmp
- STAMP_DIR    = <prefix>/src/<name>-stamp
- DOWNLOAD_DIR = <prefix>/src
- SOURCE_DIR   = <prefix>/src/<name>
- BINARY_DIR   = <prefix>/src/<name>-build
- INSTALL_DIR  = <prefix>
-
-Otherwise, if the ``EP_BASE`` directory property is set then components
-of an external project are stored under the specified base::
-
- TMP_DIR      = <base>/tmp/<name>
- STAMP_DIR    = <base>/Stamp/<name>
- DOWNLOAD_DIR = <base>/Download/<name>
- SOURCE_DIR   = <base>/Source/<name>
- BINARY_DIR   = <base>/Build/<name>
- INSTALL_DIR  = <base>/Install/<name>
-
-If no ``PREFIX``, ``EP_PREFIX``, or ``EP_BASE`` is specified then the
-default is to set ``PREFIX`` to ``<name>-prefix``.  Relative paths are
-interpreted with respect to the build directory corresponding to the
-source directory in which ``ExternalProject_Add`` is invoked.
-
-If ``SOURCE_DIR`` is explicitly set to an existing directory the project
-will be built from it.  Otherwise a download step must be specified
-using one of the ``DOWNLOAD_COMMAND``, ``CVS_*``, ``SVN_*``, or ``URL``
-options.  The ``URL`` option may refer locally to a directory or source
-tarball, or refer to a remote tarball (e.g. ``http://.../src.tgz``).
-
-The ``ExternalProject_Add_Step`` function adds a custom step to an
-external project:
-
-.. code-block:: cmake
-
- ExternalProject_Add_Step(<name> <step> # Names of project and custom step
-   [COMMAND cmd...]        # Command line invoked by this step
-   [COMMENT "text..."]     # Text printed when step executes
-   [DEPENDEES steps...]    # Steps on which this step depends
-   [DEPENDERS steps...]    # Steps that depend on this step
-   [DEPENDS files...]      # Files on which this step depends
-   [ALWAYS 1]              # No stamp file, step always runs
-   [EXCLUDE_FROM_MAIN 1]   # Main target does not depend on this step
-   [WORKING_DIRECTORY dir] # Working directory for command
-   [LOG 1]                 # Wrap step in script to log output
-   )
-
-The command line, comment, and working directory of every standard and
-custom step is processed to replace tokens ``<SOURCE_DIR>``,
-``<BINARY_DIR>``, ``<INSTALL_DIR>``, and ``<TMP_DIR>`` with
-corresponding property values.
+.. command:: ExternalProject_Add
+
+  The ``ExternalProject_Add`` function creates a custom target to drive
+  download, update/patch, configure, build, install and test steps of an
+  external project::
+
+   ExternalProject_Add(<name> [<option>...])
+
+  General options are:
+
+  ``DEPENDS <projects>...``
+    Targets on which the project depends
+  ``PREFIX <dir>``
+    Root dir for entire project
+  ``LIST_SEPARATOR <sep>``
+    Sep to be replaced by ; in cmd lines
+  ``TMP_DIR <dir>``
+    Directory to store temporary files
+  ``STAMP_DIR <dir>``
+    Directory to store step timestamps
+  ``EXCLUDE_FROM_ALL 1``
+    The "all" target does not depend on this
+
+  Download step options are:
+
+  ``DOWNLOAD_NAME <fname>``
+    File name to store (if not end of URL)
+  ``DOWNLOAD_DIR <dir>``
+    Directory to store downloaded files
+  ``DOWNLOAD_COMMAND <cmd>...``
+    Command to download source tree
+  ``DOWNLOAD_NO_PROGRESS 1``
+    Disable download progress reports
+  ``CVS_REPOSITORY <cvsroot>``
+    CVSROOT of CVS repository
+  ``CVS_MODULE <mod>``
+    Module to checkout from CVS repo
+  ``CVS_TAG <tag>``
+    Tag to checkout from CVS repo
+  ``SVN_REPOSITORY <url>``
+    URL of Subversion repo
+  ``SVN_REVISION -r<rev>``
+    Revision to checkout from Subversion repo
+  ``SVN_USERNAME <username>``
+    Username for Subversion checkout and update
+  ``SVN_PASSWORD <password>``
+    Password for Subversion checkout and update
+  ``SVN_TRUST_CERT 1``
+    Trust the Subversion server site certificate
+  ``GIT_REPOSITORY <url>``
+    URL of git repo
+  ``GIT_TAG <tag>``
+    Git branch name, commit id or tag
+  ``GIT_SUBMODULES <module>...``
+    Git submodules that shall be updated, all if empty
+  ``HG_REPOSITORY <url>``
+    URL of mercurial repo
+  ``HG_TAG <tag>``
+    Mercurial branch name, commit id or tag
+  ``URL /.../src.tgz``
+    Full path or URL of source
+  ``URL_HASH ALGO=value``
+    Hash of file at URL
+  ``URL_MD5 md5``
+    Equivalent to URL_HASH MD5=md5
+  ``TLS_VERIFY <bool>``
+    Should certificate for https be checked
+  ``TLS_CAINFO <file>``
+    Path to a certificate authority file
+  ``TIMEOUT <seconds>``
+    Time allowed for file download operations
+
+  Update/Patch step options are:
+
+  ``UPDATE_COMMAND <cmd>...``
+    Source work-tree update command
+  ``PATCH_COMMAND <cmd>...``
+    Command to patch downloaded source
+
+  Configure step options are:
+
+  ``SOURCE_DIR <dir>``
+    Source dir to be used for build
+  ``CONFIGURE_COMMAND <cmd>...``
+    Build tree configuration command
+  ``CMAKE_COMMAND /.../cmake``
+    Specify alternative cmake executable
+  ``CMAKE_GENERATOR <gen>``
+    Specify generator for native build
+  ``CMAKE_GENERATOR_PLATFORM <platform>``
+    Generator-specific platform name
+  ``CMAKE_GENERATOR_TOOLSET <toolset>``
+    Generator-specific toolset name
+  ``CMAKE_ARGS <arg>...``
+    Arguments to CMake command line
+  ``CMAKE_CACHE_ARGS <arg>...``
+    Initial cache arguments, of the form ``-Dvar:string=on``
+
+  Build step options are:
+
+  ``BINARY_DIR <dir>``
+    Specify build dir location
+  ``BUILD_COMMAND <cmd>...``
+    Command to drive the native build
+  ``BUILD_IN_SOURCE 1``
+    Use source dir for build dir
+  ``BUILD_ALWAYS 1``
+    No stamp file, build step always runs
+
+  Install step options are:
+
+  ``INSTALL_DIR <dir>``
+    Installation prefix
+  ``INSTALL_COMMAND <cmd>...``
+    Command to drive install after build
+
+  Test step options are:
+
+  ``TEST_BEFORE_INSTALL 1``
+    Add test step executed before install step
+  ``TEST_AFTER_INSTALL 1``
+    Add test step executed after install step
+  ``TEST_COMMAND <cmd>...``
+    Command to drive test
+
+  Output logging options are:
+
+  ``LOG_DOWNLOAD 1``
+    Wrap download in script to log output
+  ``LOG_UPDATE 1``
+    Wrap update in script to log output
+  ``LOG_CONFIGURE 1``
+    Wrap configure in script to log output
+  ``LOG_BUILD 1``
+    Wrap build in script to log output
+  ``LOG_TEST 1``
+    Wrap test in script to log output
+  ``LOG_INSTALL 1``
+    Wrap install in script to log output
+
+  Other options are:
+
+  ``STEP_TARGETS <step-target>...``
+    Generate custom targets for these steps
+
+  The ``*_DIR`` options specify directories for the project, with default
+  directories computed as follows.  If the ``PREFIX`` option is given to
+  ``ExternalProject_Add()`` or the ``EP_PREFIX`` directory property is set,
+  then an external project is built and installed under the specified prefix::
+
+   TMP_DIR      = <prefix>/tmp
+   STAMP_DIR    = <prefix>/src/<name>-stamp
+   DOWNLOAD_DIR = <prefix>/src
+   SOURCE_DIR   = <prefix>/src/<name>
+   BINARY_DIR   = <prefix>/src/<name>-build
+   INSTALL_DIR  = <prefix>
+
+  Otherwise, if the ``EP_BASE`` directory property is set then components
+  of an external project are stored under the specified base::
+
+   TMP_DIR      = <base>/tmp/<name>
+   STAMP_DIR    = <base>/Stamp/<name>
+   DOWNLOAD_DIR = <base>/Download/<name>
+   SOURCE_DIR   = <base>/Source/<name>
+   BINARY_DIR   = <base>/Build/<name>
+   INSTALL_DIR  = <base>/Install/<name>
+
+  If no ``PREFIX``, ``EP_PREFIX``, or ``EP_BASE`` is specified then the
+  default is to set ``PREFIX`` to ``<name>-prefix``.  Relative paths are
+  interpreted with respect to the build directory corresponding to the
+  source directory in which ``ExternalProject_Add`` is invoked.
+
+  If ``SOURCE_DIR`` is explicitly set to an existing directory the project
+  will be built from it.  Otherwise a download step must be specified
+  using one of the ``DOWNLOAD_COMMAND``, ``CVS_*``, ``SVN_*``, or ``URL``
+  options.  The ``URL`` option may refer locally to a directory or source
+  tarball, or refer to a remote tarball (e.g. ``http://.../src.tgz``).
+
+.. command:: ExternalProject_Add_Step
+
+  The ``ExternalProject_Add_Step`` function adds a custom step to an
+  external project::
+
+   ExternalProject_Add_Step(<name> <step> [<option>...])
+
+  Options are:
+
+  ``COMMAND <cmd>...``
+    Command line invoked by this step
+  ``COMMENT "<text>..."``
+    Text printed when step executes
+  ``DEPENDEES <step>...``
+    Steps on which this step depends
+  ``DEPENDERS <step>...``
+    Steps that depend on this step
+  ``DEPENDS <file>...``
+    Files on which this step depends
+  ``ALWAYS 1``
+    No stamp file, step always runs
+  ``EXCLUDE_FROM_MAIN 1``
+    Main target does not depend on this step
+  ``WORKING_DIRECTORY <dir>``
+    Working directory for command
+  ``LOG 1``
+    Wrap step in script to log output
+
+  The command line, comment, and working directory of every standard and
+  custom step is processed to replace tokens ``<SOURCE_DIR>``,
+  ``<BINARY_DIR>``, ``<INSTALL_DIR>``, and ``<TMP_DIR>`` with
+  corresponding property values.
 
 Any builtin step that specifies a ``<step>_COMMAND cmd...`` or custom
 step that specifies a ``COMMAND cmd...`` may specify additional command
@@ -142,19 +226,23 @@ specifies to run ``make`` and then ``echo done`` during the build step.
 Whether the current working directory is preserved between commands is
 not defined.  Behavior of shell operators like ``&&`` is not defined.
 
-The ``ExternalProject_Get_Property`` function retrieves external project
-target properties::
+.. command:: ExternalProject_Get_Property
 
- ExternalProject_Get_Property(<name> [prop1 [prop2 [...]]])
+  The ``ExternalProject_Get_Property`` function retrieves external project
+  target properties::
 
-It stores property values in variables of the same name.  Property
-names correspond to the keyword argument names of
-``ExternalProject_Add``.
+    ExternalProject_Get_Property(<name> [prop1 [prop2 [...]]])
 
-The ``ExternalProject_Add_StepTargets`` function generates custom
-targets for the steps listed::
+  It stores property values in variables of the same name.  Property
+  names correspond to the keyword argument names of
+  ``ExternalProject_Add``.
 
- ExternalProject_Add_StepTargets(<name> [step1 [step2 [...]]])
+.. command:: ExternalProject_Add_StepTargets
+
+  The ``ExternalProject_Add_StepTargets`` function generates custom
+  targets for the steps listed::
+
+    ExternalProject_Add_StepTargets(<name> [step1 [step2 [...]]])
 
 If ``STEP_TARGETS`` is set then ``ExternalProject_Add_StepTargets`` is
 automatically called at the end of matching calls to
@@ -201,9 +289,9 @@ file::
 math(EXPR _ep_documentation_line_count "${CMAKE_CURRENT_LIST_LINE} - 16")
 file(STRINGS "${CMAKE_CURRENT_LIST_FILE}" lines
      LIMIT_COUNT ${_ep_documentation_line_count}
-     REGEX "^ (  \\[[A-Z0-9_]+ [^]]*\\] +#.*$|[A-Za-z0-9_]+\\()")
+     REGEX "^\\.\\. command:: [A-Za-z0-9_]+|^  ``[A-Z0-9_]+ .*``$")
 foreach(line IN LISTS lines)
-  if("${line}" MATCHES "^ ([A-Za-z0-9_]+)\\(")
+  if("${line}" MATCHES "^\\.\\. command:: ([A-Za-z0-9_]+)")
     if(_ep_func)
       set(_ep_keywords_${_ep_func} "${_ep_keywords_${_ep_func}})$")
     endif()
@@ -211,8 +299,8 @@ foreach(line IN LISTS lines)
     #message("function [${_ep_func}]")
     set(_ep_keywords_${_ep_func} "^(")
     set(_ep_keyword_sep)
-  else()
-    string(REGEX REPLACE "^   \\[([A-Z0-9_]+) .*" "\\1" _ep_key "${line}")
+  elseif("${line}" MATCHES "^  ``([A-Z0-9_]+) .*``$")
+    set(_ep_key "${CMAKE_MATCH_1}")
     #message("  keyword [${_ep_key}]")
     set(_ep_keywords_${_ep_func}
       "${_ep_keywords_${_ep_func}}${_ep_keyword_sep}${_ep_key}")