Added warning to documentation about how help_foo won't be called for command foo if it uses an argparse decorator

Also:
- Renamed argparse_example.py to decorator_example.py

Author: tleonhardt

CHANGELOG.md

@@ -34,6 +34,7 @@
             * Never - output methods strip all ANSI escape sequences
     * Added ``macro`` command to create macros, which are similar to aliases, but can take arguments when called
     * All cmd2 command functions have been converted to use argparse.
+    * Renamed argparse_example.py to decorator_example.py to help clarify its intent
 * Deprecations
     * Deprecated the built-in ``cmd2`` support for colors including ``Cmd.colorize()`` and ``Cmd._colorcodes``
 * Deletions (potentially breaking changes)

docs/argument_processing.rst

@@ -15,11 +15,11 @@ Argument Processing
 
 These features are all provided by the ``@with_argparser`` decorator which is importable from ``cmd2``.
 
-See the either the argprint_ or argparse_ example to learn more about how to use the various ``cmd2`` argument
+See the either the argprint_ or decorator_ example to learn more about how to use the various ``cmd2`` argument
 processing decorators in your ``cmd2`` applications.
 
 .. _argprint: https://github.com/python-cmd2/cmd2/blob/master/examples/arg_print.py
-.. _argparse: https://github.com/python-cmd2/cmd2/blob/master/examples/argparse_example.py
+.. _decorator: https://github.com/python-cmd2/cmd2/blob/master/examples/decorator_example.py
 
 Using the argument parser decorator
 ===================================
@@ -171,6 +171,14 @@ Which yields:
 
    This command can not generate tags with no content, like <br/>
 
+.. warning::
+
+    If a command **foo** is decorated with one of cmd2's argparse decorators, then **help_foo** will not
+    be invoked when ``help foo`` is called.  The argparse_ module provides a rich API which can be used to
+    tweak every aspect of the displayed help and we encourage ``cmd2`` developers to utilize that.
+
+.. _argparse: https://docs.python.org/3/library/argparse.html
+
 
 Grouping Commands
 =================

examples/argparse_example.py examples/decorator_example.pyexamples/argparse_example.py renamed to examples/decorator_example.py

@@ -1,14 +1,13 @@
 #!/usr/bin/env python
 # coding=utf-8
-"""A sample application for cmd2 showing how to use argparse to
+"""A sample application showing how to use cmd2's argparse decorators to
 process command line arguments for your application.
 
 Thanks to cmd2's built-in transcript testing capability, it also
-serves as a test suite for argparse_example.py when used with the
-exampleSession.txt transcript.
+serves as a test suite when used with the exampleSession.txt transcript.
 
-Running `python argparse_example.py -t exampleSession.txt` will run
-all the commands in the transcript against argparse_example.py,
+Running `python decorator_example.py -t exampleSession.txt` will run
+all the commands in the transcript against decorator_example.py,
 verifying that the output produced matches the transcript.
 """
 import argparse

examples/transcripts/exampleSession.txt

@@ -1,4 +1,4 @@
-# Run this transcript with "python argparse_example.py -t exampleSession.txt"
+# Run this transcript with "python decorator_example.py -t exampleSession.txt"
 # The regex for colors is because no color on Windows.
 # The regex for editor will match whatever program you use.
 # regexes on prompts just make the trailing space obvious