From 8e2a591be5a6f80024b0ab5c7991478dec9e2804 2011-07-13 21:23:58 From: Brian Granger Date: 2011-07-13 21:23:58 Subject: [PATCH] Command line examples added for non-parallel apps. --- diff --git a/IPython/config/application.py b/IPython/config/application.py index 3a48295..95a01a2 100644 --- a/IPython/config/application.py +++ b/IPython/config/application.py @@ -89,7 +89,9 @@ class Application(SingletonConfigurable): option_description = Unicode(option_description) keyvalue_description = Unicode(keyvalue_description) subcommand_description = Unicode(subcommand_description) - + + # The usage and example string that goes at the end of the help string. + examples = Unicode() # A sequence of Configurable subclasses whose config=True attributes will # be exposed at the command line. @@ -170,7 +172,7 @@ class Application(SingletonConfigurable): self._log_formatter = logging.Formatter("[%(name)s] %(message)s") self._log_handler.setFormatter(self._log_formatter) self.log.addHandler(self._log_handler) - + def initialize(self, argv=None): """Do the basic steps to configure me. @@ -285,6 +287,19 @@ class Application(SingletonConfigurable): print p print + def print_examples(self): + """Print usage and examples. + + This usage string goes at the end of the command line help string + and should contain examples of the application's usage. + """ + if self.examples: + print "Examples" + print "--------" + print + print indent(dedent(self.examples.strip())) + print + def print_version(self): """Print the version string.""" print self.version @@ -327,6 +342,7 @@ class Application(SingletonConfigurable): if '-h' in argv or '--help' in argv or '--help-all' in argv: self.print_description() self.print_help('--help-all' in argv) + self.print_examples() self.exit(0) if '--version' in argv: @@ -341,6 +357,7 @@ class Application(SingletonConfigurable): except (TraitError, ArgumentError) as e: self.print_description() self.print_help() + self.print_examples() self.log.fatal(str(e)) self.exit(1) # store unparsed args in extra_args diff --git a/IPython/core/profileapp.py b/IPython/core/profileapp.py index d3220cb..a4e9112 100644 --- a/IPython/core/profileapp.py +++ b/IPython/core/profileapp.py @@ -79,7 +79,6 @@ where you can edit ipython_config.py to start configuring IPython. #----------------------------------------------------------------------------- - class ProfileList(Application): name = u'ipython-profile' description = list_help @@ -128,9 +127,15 @@ 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 auto_create = Bool(True, config=False) def _copy_config_files_default(self): @@ -199,10 +204,16 @@ 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 + subcommands = Dict(dict( create = (ProfileCreate, "Create a new profile dir with default config files"), list = (ProfileList, "List existing profiles") diff --git a/IPython/frontend/qt/console/qtconsoleapp.py b/IPython/frontend/qt/console/qtconsoleapp.py index dcf7fd6..4825564 100644 --- a/IPython/frontend/qt/console/qtconsoleapp.py +++ b/IPython/frontend/qt/console/qtconsoleapp.py @@ -218,6 +218,12 @@ 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' default_config_file_name='ipython_config.py' @@ -231,7 +237,8 @@ class IPythonQtConsoleApp(BaseIPythonApplication): The QtConsole supports various extra features beyond the """ - + examples = qt_examples + classes = [IPKernelApp, IPythonWidget, ZMQInteractiveShell, ProfileDir, Session] flags = Dict(flags) aliases = Dict(aliases) diff --git a/IPython/frontend/terminal/ipapp.py b/IPython/frontend/terminal/ipapp.py index 2c37b4d..56faf24 100755 --- a/IPython/frontend/terminal/ipapp.py +++ b/IPython/frontend/terminal/ipapp.py @@ -168,12 +168,23 @@ 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 + flags = Dict(flags) aliases = Dict(aliases) classes = [InteractiveShellApp, TerminalInteractiveShell, ProfileDir, PlainTextFormatter]