Help¶
From our experience, end users rarely read documentation no matter how high-
quality or useful that documentation might be. So it is important that you
provide good built-in help within your application. Fortunately, cmd2
makes this easy.
Getting Help¶
cmd2
makes it easy for end users of cmd2
applications to get help via
the built-in help
command. The help
command by itself displays a list
of the commands available:
(Cmd) help
Documented commands (use 'help -v' for verbose/'help <topic>' for details):
===========================================================================
alias help ipy py run_pyscript set shortcuts
edit history macro quit run_script shell
The help
command can also be used to provide detailed help for a specific
command:
(Cmd) help quit
Usage: quit [-h]
Exit this application
optional arguments:
-h, --help show this help message and exit
Providing Help¶
cmd2
makes it easy for developers of cmd2
applications to provide this
help. By default, the help for a command is the docstring for the do_*
method defining the command - e.g. for a command foo, that command is
implementd by defining the do_foo
method and the docstring for that method
is the help.
For commands which use one of the argparse
decorators to parse arguments,
help is provided by argparse
. See
Help Messages for more information.
Occasionally there might be an unusual circumstance where providing static help
text isn’t good enough and you want to provide dynamic information in the help
text for a command. To meet this need, if a help_foo
method is defined to
match the do_foo
method, then that method will be used to provide the help
for command foo. This dynamic help is only supported for commands which
do not use an argparse
decorator because didn’t want different output for
help cmd
than for cmd -h
.
Categorizing Commands¶
By default, the help
command displays:
Documented commands (use 'help -v' for verbose/'help <topic>' for details):
===========================================================================
alias help ipy py run_pyscript set shortcuts
edit history macro quit run_script shell
If you have a large number of commands, you can optionally group your commands
into categories. Here’s the output from the example help_categories.py
:
Documented commands (use 'help -v' for verbose/'help <topic>' for details):
Application Management
======================
deploy findleakers redeploy sessions stop
expire list restart start undeploy
Command Management
==================
disable_commands enable_commands
Connecting
==========
connect which
Server Information
==================
resources serverinfo sslconnectorciphers status thread_dump vminfo
Other
=====
alias edit history py run_pyscript set shortcuts
config help macro quit run_script shell version
There are 2 methods of specifying command categories, using the
@with_category
decorator or with the categorize()
function. Once a
single command category is detected, the help output switches to a categorized
mode of display. All commands with an explicit category defined default to the
category Other.
Using the @with_category
decorator:
@with_category(CMD_CAT_CONNECTING)
def do_which(self, _):
"""Which command"""
self.poutput('Which')
Using the categorize()
function:
You can call with a single function:
def do_connect(self, _): """Connect command""" self.poutput('Connect') # Tag the above command functions under the category Connecting categorize(do_connect, CMD_CAT_CONNECTING)Or with an Iterable container of functions:
def do_undeploy(self, _): """Undeploy command""" self.poutput('Undeploy') def do_stop(self, _): """Stop command""" self.poutput('Stop') def do_findleakers(self, _): """Find Leakers command""" self.poutput('Find Leakers') # Tag the above command functions under the category Application Management categorize((do_undeploy, do_stop, do_findleakers), CMD_CAT_APP_MGMT)
The help
command also has a verbose option (help -v
or help
--verbose
) that combines the help categories with per-command Help Messages:
Documented commands (use 'help -v' for verbose/'help <topic>' for details):
Application Management
================================================================================
deploy Deploy command
expire Expire command
findleakers Find Leakers command
list List command
redeploy Redeploy command
restart usage: restart [-h] {now,later,sometime,whenever}
sessions Sessions command
start Start command
stop Stop command
undeploy Undeploy command
Connecting
================================================================================
connect Connect command
which Which command
Server Information
================================================================================
resources Resources command
serverinfo Server Info command
sslconnectorciphers SSL Connector Ciphers command is an example of a command that contains
multiple lines of help information for the user. Each line of help in a
contiguous set of lines will be printed and aligned in the verbose output
provided with 'help --verbose'
status Status command
thread_dump Thread Dump command
vminfo VM Info command
Other
================================================================================
alias Manage aliases
config Config command
edit Run a text editor and optionally open a file with it
help List available commands or provide detailed help for a specific command
history View, run, edit, save, or clear previously entered commands
macro Manage macros
py Invoke Python command or shell
quit Exits this application
run_pyscript Runs a python script file inside the console
run_script Runs commands in script file that is encoded as either ASCII or UTF-8 text
set Set a settable parameter or show current settings of parameters
shell Execute a command as if at the OS prompt
shortcuts List available shortcuts
version Version command
When called with the -v
flag for verbose help, the one-line description for
each command is provided by the first line of the docstring for that command’s
associated do_*
method.