Consider categorizing output of 'help' command

[kotfu]

Right now the help command just gives you an alphabetical columnar list of commands. It would be nice if there was a way to create groups or categories of commands, so you could have related commands show up together.

Instead of this:

Documented commands (type help <topic>):
========================================
config     expire       load      resources   shell                stop
connect    findleakers  py        restart     shortcuts            threaddump
deploy     help         pyscript  serverinfo  show                 undeploy
edit       history      quit      sessions    sslconnectorciphers  version
exit       license      redeploy  set         start                vminfo
exit_code  list         reload    settings    status               which

It would be nice if you could create something like:

Documented commands (for more info type help <command>)

Connecting
=========================================
connect     which

Application Management
=========================================
list
deploy       redeploy      undeploy
start        restart       stop
sessions     expire        findleakers

Server Information
==========================================
resources         serverinfo      sslconnectorciphers
status            thread dump     vminfo

Settings
==========================================
config       set           show

Other
=============================
edit      help        license
exit      history     load
version

It would be great if you could not only control the sections of the help, but the order and formatting of the commands within each section. Commands not specified for inclusion in a specific section would be featured in a catch all section like Other.

It might also be interesting to have a way to specify a short phrase of help for each command, with some command like help --long to show:

Documented commands (for more info type help <command>)

Connecting
=========================================
connect    connect to a tomcat server
which      show which server you are currently connected to
...

[tleonhardt]

I really like the concept of having categories of commands which get displayed together in the help menu, particularly if this is an opt-in capability which defaults to the current behavior. That would be a nice addition.

Potentially of relevance, the existing behavior actually divides the help menu into three categories:

• Documented commands
  • A do_foo method exists which has a docstring and/or an associated help_foo method
• Miscellaneous
  • A help_foo method exists, but there is no corresponding do_foo
• Undocumented commands
  • A do_foo method exists which does not have a docstring or an associated help_foo method

[anselor]

I just added a low-impact implementation of help categories in the help_categories branch.
Let me know what you guys think of this approach.

For the help --long (or maybe help --verbose), I was thinking just take the first non-empty line of function docstring used in the help for the command. Any thoughts?

[tleonhardt]

@anselor cmd2 will still be supporting Python 2.7 until the end of August 2018. Optional type hinting is only available in Python 3. So you will need to remove your usage of optional type hinting.

Also, there appear to be a lot of unit test failures for every version of Python other than 3.5. We currently support versions 2.7, 3.4, 3.5, 3.6, and 3.7.

But the basic architecture of your changes looks pretty clean to me.

[tleonhardt]

If recommend setting up multiple versions of Python in different virtual environments for testing. This can be done either using the conda package manager which comes with the Anaconda distribution or the virtualenv module.

[tleonhardt]

@anselor If you haven't already, check out the Contributing Guide for advice on how to run the unit tests and such.

[anselor]

help -v / help --verbose