From 01ecd24fa60c40b0fefab3f100f308799ef754c9 Mon Sep 17 00:00:00 2001 From: Brad King Date: Tue, 19 Nov 2013 09:27:08 -0500 Subject: [PATCH] ExternalProject: Format module documentation Manually revise the .rst format of the documentation. Use inline literal quotes appropriately in paragraph text. Move the :: literal block openers to the end of the preceding paragraphs. Convert the command signature documentation and examples to cmake code-block directives. --- Modules/ExternalProject.cmake | 129 ++++++++++++++++------------------ 1 file changed, 59 insertions(+), 70 deletions(-) diff --git a/Modules/ExternalProject.cmake b/Modules/ExternalProject.cmake index 84fa61377..63f11802e 100644 --- a/Modules/ExternalProject.cmake +++ b/Modules/ExternalProject.cmake @@ -4,11 +4,11 @@ # # Create custom targets to build projects in external trees # -# The 'ExternalProject_Add' function creates a custom target to drive +# 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 for custom target # [DEPENDS projects...] # Targets on which the project depends @@ -72,46 +72,42 @@ # ) # # 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: +# 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 = /tmp +# STAMP_DIR = /src/-stamp +# DOWNLOAD_DIR = /src +# SOURCE_DIR = /src/ +# BINARY_DIR = /src/-build +# INSTALL_DIR = # -# TMP_DIR = /tmp -# STAMP_DIR = /src/-stamp -# DOWNLOAD_DIR = /src -# SOURCE_DIR = /src/ -# BINARY_DIR = /src/-build -# INSTALL_DIR = +# Otherwise, if the ``EP_BASE`` directory property is set then components +# of an external project are stored under the specified base:: # -# Otherwise, if the EP_BASE directory property is set then components of -# an external project are stored under the specified base: +# TMP_DIR = /tmp/ +# STAMP_DIR = /Stamp/ +# DOWNLOAD_DIR = /Download/ +# SOURCE_DIR = /Source/ +# BINARY_DIR = /Build/ +# INSTALL_DIR = /Install/ # -# :: +# If no ``PREFIX``, ``EP_PREFIX``, or ``EP_BASE`` is specified then the +# default is to set ``PREFIX`` to ``-prefix``. Relative paths are +# interpreted with respect to the build directory corresponding to the +# source directory in which ``ExternalProject_Add`` is invoked. # -# TMP_DIR = /tmp/ -# STAMP_DIR = /Stamp/ -# DOWNLOAD_DIR = /Download/ -# SOURCE_DIR = /Source/ -# BINARY_DIR = /Build/ -# INSTALL_DIR = /Install/ -# -# If no PREFIX, EP_PREFIX, or EP_BASE is specified then the default is -# to set PREFIX to "-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 +# 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). +# 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 +# The ``ExternalProject_Add_Step`` function adds a custom step to an # external project: # -# :: +# .. code-block:: cmake # # ExternalProject_Add_Step( # Names of project and custom step # [COMMAND cmd...] # Command line invoked by this step @@ -125,51 +121,45 @@ # ) # # The command line, comment, and working directory of every standard and -# custom step is processed to replace tokens , , -# , and with corresponding property values. +# custom step is processed to replace tokens ````, +# ````, ````, and ```` with +# corresponding property values. # -# Any builtin step that specifies a "_COMMAND cmd..." or custom -# step that specifies a "COMMAND cmd..." may specify additional command -# lines using the form "COMMAND cmd...". At build time the commands -# will be executed in order and aborted if any one fails. For example: +# Any builtin step that specifies a ``_COMMAND cmd...`` or custom +# step that specifies a ``COMMAND cmd...`` may specify additional command +# lines using the form ``COMMAND cmd...``. At build time the commands +# will be executed in order and aborted if any one fails. For example:: # -# :: +# ... BUILD_COMMAND make COMMAND echo done ... # -# ... BUILD_COMMAND make COMMAND echo done ... -# -# specifies to run "make" and then "echo done" during the build step. +# 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. +# not defined. Behavior of shell operators like ``&&`` is not defined. # -# The 'ExternalProject_Get_Property' function retrieves external project -# target properties: +# The ``ExternalProject_Get_Property`` function retrieves external project +# target properties:: # -# :: -# -# ExternalProject_Get_Property( [prop1 [prop2 [...]]]) +# ExternalProject_Get_Property( [prop1 [prop2 [...]]]) # # It stores property values in variables of the same name. Property # names correspond to the keyword argument names of -# 'ExternalProject_Add'. +# ``ExternalProject_Add``. # -# The 'ExternalProject_Add_StepTargets' function generates custom -# targets for the steps listed: +# The ``ExternalProject_Add_StepTargets`` function generates custom +# targets for the steps listed:: # -# :: +# ExternalProject_Add_StepTargets( [step1 [step2 [...]]]) # -# ExternalProject_Add_StepTargets( [step1 [step2 [...]]]) -# -# -# -# If STEP_TARGETS is set then ExternalProject_Add_StepTargets is +# If ``STEP_TARGETS`` is set then ``ExternalProject_Add_StepTargets`` is # automatically called at the end of matching calls to -# ExternalProject_Add_Step. Pass STEP_TARGETS explicitly to individual -# ExternalProject_Add calls, or implicitly to all ExternalProject_Add -# calls by setting the directory property EP_STEP_TARGETS. +# ``ExternalProject_Add_Step``. Pass ``STEP_TARGETS`` explicitly to +# individual ``ExternalProject_Add`` calls, or implicitly to all +# ``ExternalProject_Add`` calls by setting the directory property +# ``EP_STEP_TARGETS``. # -# If STEP_TARGETS is not set, clients may still manually call -# ExternalProject_Add_StepTargets after calling ExternalProject_Add or -# ExternalProject_Add_Step. +# If ``STEP_TARGETS`` is not set, clients may still manually call +# ``ExternalProject_Add_StepTargets`` after calling +# ``ExternalProject_Add`` or ``ExternalProject_Add_Step``. # # This functionality is provided to make it easy to drive the steps # independently of each other by specifying targets on build command @@ -181,15 +171,14 @@ # will also run to ensure everything is up to date. # # For example, to drive configure, build and test steps independently -# for each ExternalProject_Add call in your project, write the following -# line prior to any ExternalProject_Add calls in your CMakeLists file: +# for each ``ExternalProject_Add`` call in your project, write the following +# line prior to any ``ExternalProject_Add`` calls in your ``CMakeLists.txt`` +# file:: # -# :: -# -# set_property(DIRECTORY PROPERTY EP_STEP_TARGETS configure build test) +# set_property(DIRECTORY PROPERTY EP_STEP_TARGETS configure build test) #============================================================================= -# Copyright 2008-2012 Kitware, Inc. +# Copyright 2008-2013 Kitware, Inc. # # Distributed under the OSI-approved BSD License (the "License"); # see accompanying file Copyright.txt for details.