Added better documentation to command line programs.

IPython/kernel/ipclusterapp.py

@@ -171,10 +171,22 b' class IPClusterCLLoader(ArgParseConfigLoader):'
 default_config_file_name = u'ipcluster_config.py'
 
 
+_description = """Start an IPython cluster for parallel computing.\n\n
+
+An IPython cluster consists of 1 controller and 1 or more engines.
+This command automates the startup of these processes using a wide
+range of startup methods (SSH, local processes, PBS, mpiexec,
+Windows HPC Server 2008). To start a cluster with 4 engines on your
+local host simply do "ipcluster start -n 4". For more complex usage 
+you will typically do "ipcluster create -p mycluster", then edit
+configuration files, followed by "ipcluster start -p mycluster -n 4".
+"""
+
+
 class IPClusterApp(ApplicationWithClusterDir):
 
     name = u'ipcluster'
-    description = 'Start an IPython cluster (controller and engines).'
+    description = _description
     config_file_name = default_config_file_name
     default_log_level = logging.INFO
     auto_create_cluster_dir = False

IPython/kernel/ipcontrollerapp.py

@@ -176,13 +176,23 b' class IPControllerAppCLConfigLoader(AppWithClusterDirArgParseConfigLoader):'
     arguments = cl_args
 
 
+_description = """Start the IPython controller for parallel computing.
+
+The IPython controller provides a gateway between the IPython engines and
+clients. The controller needs to be started before the engines and can be
+configured using command line options or using a cluster directory. Cluster
+directories contain config, log and security files and are usually located in
+your .ipython directory and named as "cluster_<profile>". See the --profile
+and --cluster-dir options for details.
+"""
+
 default_config_file_name = u'ipcontroller_config.py'
 
 
 class IPControllerApp(ApplicationWithClusterDir):
 
     name = u'ipcontroller'
-    description = 'Start the IPython controller for parallel computing.'
+    description = _description
     config_file_name = default_config_file_name
     auto_create_cluster_dir = True
 

IPython/kernel/ipengineapp.py

@@ -87,10 +87,21 b' mpi.size = 0'
 default_config_file_name = u'ipengine_config.py'
 
 
+_description = """Start an IPython engine for parallel computing.\n\n
+
+IPython engines run in parallel and perform computations on behalf of a client
+and controller. A controller needs to be started before the engines. The
+engine can be configured using command line options or using a cluster
+directory. Cluster directories contain config, log and security files and are
+usually located in your .ipython directory and named as "cluster_<profile>".
+See the --profile and --cluster-dir options for details.
+"""
+
+
 class IPEngineApp(ApplicationWithClusterDir):
 
     name = u'ipengine'
-    description = 'Start the IPython engine for parallel computing.'
+    description = _description
     config_file_name = default_config_file_name
     auto_create_cluster_dir = True