Merge pull request #867 from python-cmd2/discoverable_verbose_help

Make verbose help more discoverable

Author: tleonhardt

CHANGELOG.md

@@ -1,4 +1,6 @@
 ## 0.9.26 (TBD, 2020)
+* Enhancements
+    * Changed the default help text to make `help -v` more discoverable
 * Breaking changes
     * Renamed `locals_in_py` attribute of `cmd2.Cmd` to `self_in_py`
     * The following public attributes of `cmd2.Cmd` are no longer settable at runtime by end users:

cmd2/cmd2.py

@@ -279,6 +279,9 @@ def __init__(self, completekey: str = 'tab', stdin=None, stdout=None, *,
         # The multiline command currently being typed which is used to tab complete multiline commands.
         self._multiline_in_progress = ''
 
+        # Set the header used for the help function's listing of documented functions
+        self.doc_header = "Documented commands (use 'help -v' for verbose/'help <topic>' for details):"
+
         # The error that prints when no help information can be found
         self.help_error = "No help on {}"
 

docs/features/help.rst

@@ -12,15 +12,15 @@ Categorizing Commands
 
 By default, the ``help`` command displays::
 
-  Documented commands (type help <topic>):
-  ========================================
+  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 (type help <topic>):
+  Documented commands (use 'help -v' for verbose/'help <topic>' for details):
 
   Application Management
   ======================
@@ -90,7 +90,7 @@ Using the ``categorize()`` function:
 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 (type help <topic>):
+    Documented commands (use 'help -v' for verbose/'help <topic>' for details):
 
     Application Management
     ================================================================================

docs/features/initialization.rst

@@ -108,6 +108,8 @@ override:
   support commands that are only available during specific states of the
   application. This dictionary's keys are the command names and its values are
   DisabledCommand objects.
+- **doc_header**: Set the header used for the help function's listing of
+  documented functions
 - **echo**: if ``True``, each command the user issues will be repeated to the
   screen before it is executed. This is particularly useful when running
   scripts. This behavior does not occur when running a command at the prompt.

docs/features/os.rst

@@ -49,8 +49,8 @@ loop::
 
     $ python examples/example.py help
 
-    Documented commands (type help <topic>):
-    ========================================
+    Documented commands (use 'help -v' for verbose/'help <topic>' for details):
+    ===========================================================================
     alias  help     macro   orate  quit          run_script  set    shortcuts
     edit   history  mumble  py     run_pyscript  say         shell  speak