From 52c402a6ac96ecda5a7893ca79416b093d6b9208 2009-11-15 23:56:14
From: Brian Granger <ellisonbg@gmail.com>
Date: 2009-11-15 23:56:14
Subject: [PATCH] Added better documentation to command line programs.

---

diff --git a/IPython/kernel/ipclusterapp.py b/IPython/kernel/ipclusterapp.py
index 773336d..fe74e83 100644
--- a/IPython/kernel/ipclusterapp.py
+++ b/IPython/kernel/ipclusterapp.py
@@ -171,10 +171,22 @@ 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
diff --git a/IPython/kernel/ipcontrollerapp.py b/IPython/kernel/ipcontrollerapp.py
index 02cc1e6..70ce723 100644
--- a/IPython/kernel/ipcontrollerapp.py
+++ b/IPython/kernel/ipcontrollerapp.py
@@ -176,13 +176,23 @@ 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
 
diff --git a/IPython/kernel/ipengineapp.py b/IPython/kernel/ipengineapp.py
index 4a2a879..9edc72b 100644
--- a/IPython/kernel/ipengineapp.py
+++ b/IPython/kernel/ipengineapp.py
@@ -87,10 +87,21 @@ 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