From b9ade301965458a3f605101ef1e5d55347743910 2011-07-13 21:25:26 From: Brian Granger Date: 2011-07-13 21:25:26 Subject: [PATCH] More work on adding examples to help strings. --- diff --git a/IPython/core/profileapp.py b/IPython/core/profileapp.py index a4e9112..3efe80b 100644 --- a/IPython/core/profileapp.py +++ b/IPython/core/profileapp.py @@ -74,6 +74,18 @@ where you can edit ipython_config.py to start configuring IPython. """ +_list_examples = "ipython profile list # list all profiles" + +_create_examples = """ +ipython profile create foo # create profile foo +ipython profile create foo --init # create with default config files +""" + +_main_examples = """ +ipython profile create -h # show the help string for the create subcommand +ipython profile list -h # show the help string for the list subcommand +""" + #----------------------------------------------------------------------------- # Profile Application Class (for `ipython profile` subcommand) #----------------------------------------------------------------------------- @@ -82,7 +94,8 @@ where you can edit ipython_config.py to start configuring IPython. class ProfileList(Application): name = u'ipython-profile' description = list_help - + examples = _list_examples + aliases = Dict({ 'ipython-dir' : 'ProfileList.ipython_dir', 'log-level' : 'Application.log_level', @@ -92,6 +105,7 @@ class ProfileList(Application): "Set Application.log_level to 0, maximizing log output." ) )) + ipython_dir = Unicode(get_ipython_dir(), config=True, help=""" The name of the IPython directory. This directory is used for logging @@ -127,15 +141,11 @@ create_flags.update(boolean_flag('parallel', 'ProfileCreate.parallel', "Include parallel computing config files", "Don't include parallel computing config files")) -create_examples = """ -ipython profile create foo # create profile foo -ipython profile create foo --init # create with default config files -""" class ProfileCreate(BaseIPythonApplication): name = u'ipython-profile' description = create_help - examples = create_examples + examples = _create_examples auto_create = Bool(True, config=False) def _copy_config_files_default(self): @@ -204,15 +214,11 @@ class ProfileCreate(BaseIPythonApplication): def stage_default_config_file(self): pass -main_examples = """ -ipython profile create -h # show the help string for the create subcommand -ipython profile list -h # show the help string for the list subcommand -""" class ProfileApp(Application): name = u'ipython-profile' description = profile_help - examples = main_examples + examples = _main_examples subcommands = Dict(dict( create = (ProfileCreate, "Create a new profile dir with default config files"), diff --git a/IPython/frontend/qt/console/qtconsoleapp.py b/IPython/frontend/qt/console/qtconsoleapp.py index 4825564..ea478a2 100644 --- a/IPython/frontend/qt/console/qtconsoleapp.py +++ b/IPython/frontend/qt/console/qtconsoleapp.py @@ -53,6 +53,15 @@ from IPython.zmq.zmqshell import ZMQInteractiveShell from IPython.utils.localinterfaces import LOCALHOST, LOCAL_IPS #----------------------------------------------------------------------------- +# Globals +#----------------------------------------------------------------------------- + +_examples = """ +ipython qtconsole # start the qtconsole +ipython qtconsole --pylab=inline # start with pylab in inline plotting mode +""" + +#----------------------------------------------------------------------------- # Classes #----------------------------------------------------------------------------- @@ -219,10 +228,6 @@ aliases.update(dict( # IPythonQtConsole #----------------------------------------------------------------------------- -qt_examples = """ -ipython qtconsole # start the qtconsole -ipython qtconsole --pylab=inline # start with pylab in inline plotting mode -""" class IPythonQtConsoleApp(BaseIPythonApplication): name = 'ipython-qtconsole' @@ -237,7 +242,7 @@ class IPythonQtConsoleApp(BaseIPythonApplication): The QtConsole supports various extra features beyond the """ - examples = qt_examples + examples = _examples classes = [IPKernelApp, IPythonWidget, ZMQInteractiveShell, ProfileDir, Session] flags = Dict(flags) diff --git a/IPython/frontend/terminal/ipapp.py b/IPython/frontend/terminal/ipapp.py index 56faf24..e9c7852 100755 --- a/IPython/frontend/terminal/ipapp.py +++ b/IPython/frontend/terminal/ipapp.py @@ -58,6 +58,15 @@ from IPython.utils.traitlets import ( #: The default config file name for this application. default_config_file_name = u'ipython_config.py' +_examples = """ +ipython --pylab # start in pylab mode +ipython --pylab=qt # start in pylab mode with the qt4 backend +ipython --log_level=DEBUG # set logging to DEBUG +ipython --profile=foo # start with profile foo +ipython qtconsole # start the qtconsole GUI application +ipython profile -h # show the help string for the profile subcmd +ipython qtconsole -h # show the help string for the qtconsole subcmd +""" #----------------------------------------------------------------------------- # Crash handler for this application @@ -168,22 +177,13 @@ aliases.update(dict( # Main classes and functions #----------------------------------------------------------------------------- -examples = """ -ipython --pylab # start in pylab mode -ipython --pylab=qt # start in pylab mode with the qt4 backend -ipython --log_level=DEBUG # set logging to DEBUG -ipython --profile=foo # start with profile foo -ipython qtconsole # start the qtconsole GUI application -ipython profile -h # show the help string for the profile subcmd -ipython qtconsole -h # show the help string for the qtconsole subcmd -""" class TerminalIPythonApp(BaseIPythonApplication, InteractiveShellApp): name = u'ipython' description = usage.cl_usage default_config_file_name = default_config_file_name crash_handler_class = IPAppCrashHandler - examples = examples + examples = _examples flags = Dict(flags) aliases = Dict(aliases) diff --git a/IPython/parallel/apps/ipclusterapp.py b/IPython/parallel/apps/ipclusterapp.py index a294b58..0a9e7c9 100755 --- a/IPython/parallel/apps/ipclusterapp.py +++ b/IPython/parallel/apps/ipclusterapp.py @@ -61,9 +61,28 @@ 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 profile=mycluster', then edit -configuration files, followed by 'ipcluster start profile=mycluster n=4'. +local host simply do 'ipcluster start --n=4'. For more complex usage +you will typically do 'ipython create mycluster --parallel', then edit +configuration files, followed by 'ipcluster start --profile=mycluster --n=4'. +""" + +_main_examples = """ +ipcluster start -h # show the help string for the start subcmd +ipcluster stop -h # show the help string for the stop subcmd +ipcluster engines -h # show the help string for the engines subcmd +""" + +_start_examples = """ +ipython profile create mycluster --parallel # create mycluster profile +ipcluster start --profile=mycluster --n=4 # start mycluster with 4 nodes +""" + +_stop_examples = """ +ipcluster stop --profile=mycluster # stop a running cluster by profile name +""" + +_engines_examples = """ +ipcluster engines --profile=mycluster --n=4 # start 4 engines only """ @@ -126,6 +145,7 @@ stop_aliases.update(base_aliases) class IPClusterStop(BaseParallelApplication): name = u'ipcluster' description = stop_help + examples = _stop_examples config_file_name = Unicode(default_config_file_name) signal = Int(signal.SIGINT, config=True, @@ -195,6 +215,7 @@ class IPClusterEngines(BaseParallelApplication): name = u'ipcluster' description = engines_help + examples = _engines_examples usage = None config_file_name = Unicode(default_config_file_name) default_log_level = logging.INFO @@ -329,6 +350,7 @@ class IPClusterStart(IPClusterEngines): name = u'ipcluster' description = start_help + examples = _start_examples default_log_level = logging.INFO auto_create = Bool(True, config=True, help="whether to create the profile_dir if it doesn't exist") @@ -426,7 +448,8 @@ base='IPython.parallel.apps.ipclusterapp.IPCluster' class IPClusterApp(Application): name = u'ipcluster' description = _description - + examples = _main_examples + subcommands = { 'start' : (base+'Start', start_help), 'stop' : (base+'Stop', stop_help), diff --git a/IPython/parallel/apps/ipcontrollerapp.py b/IPython/parallel/apps/ipcontrollerapp.py index 23416bd..858ac16 100755 --- a/IPython/parallel/apps/ipcontrollerapp.py +++ b/IPython/parallel/apps/ipcontrollerapp.py @@ -85,7 +85,10 @@ your ipython directory and named as "profile_name". See the `profile` and `profile_dir` options for details. """ - +_examples = """ +ipcontroller --ip=192.168.0.1 --port=1000 # listen on ip, port for engines +ipcontroller --scheme=pure # use the pure zeromq scheduler +""" #----------------------------------------------------------------------------- @@ -131,10 +134,12 @@ aliases = dict( ) aliases.update(base_aliases) + class IPControllerApp(BaseParallelApplication): name = u'ipcontroller' description = _description + examples = _examples config_file_name = Unicode(default_config_file_name) classes = [ProfileDir, Session, HubFactory, TaskScheduler, HeartMonitor, SQLiteDB] + maybe_mongo diff --git a/IPython/parallel/apps/ipengineapp.py b/IPython/parallel/apps/ipengineapp.py index 0dcdd61..601d21d 100755 --- a/IPython/parallel/apps/ipengineapp.py +++ b/IPython/parallel/apps/ipengineapp.py @@ -64,6 +64,10 @@ usually located in your ipython directory and named as "profile_name". See the `profile` and `profile_dir` options for details. """ +_examples = """ +ipengine --ip=192.168.0.1 --port=1000 # connect to hub at ip and port +ipengine --log_to_file --log_level=DEBUG # log to a file with DEBUG verbosity +""" #----------------------------------------------------------------------------- # MPI configuration @@ -126,10 +130,12 @@ aliases = dict( ) aliases.update(base_aliases) + class IPEngineApp(BaseParallelApplication): name = Unicode(u'ipengine') description = Unicode(_description) + examples = _examples config_file_name = Unicode(default_config_file_name) classes = List([ProfileDir, Session, EngineFactory, Kernel, MPI])