Simplified a few argparse examples and fixed some incorrect documentation

I eliminated a few "narg=1" configurations so that a single str value is returned instead of a List[str].

I also reworded some documentation which was no longer correct after the last commit which made "history command" have the same help text as "command -h" when using one of the two argparse decorators.

Author: tleonhardt

docs/argument_processing.rst

@@ -58,25 +58,26 @@ Help Messages
 
 By default, cmd2 uses the docstring of the command method when a user asks
 for help on the command. When you use the ``@with_argument_parser``
-decorator, the formatted help from the ``argparse.ArgumentParser`` is
-appended to the docstring for the method of that command. With this code::
+decorator, the docstring for the ``do_*`` method is used to set the description for the ``argparse.ArgumentParser`` is
+With this code::
 
    argparser = argparse.ArgumentParser()
-   argparser.add_argument('tag', nargs=1, help='tag')
+   argparser.add_argument('tag', help='tag')
    argparser.add_argument('content', nargs='+', help='content to surround with tag')
    @with_argument_parser(argparser)
    def do_tag(self, args):
       """create a html tag"""
-      self.stdout.write('<{0}>{1}</{0}>'.format(args.tag[0], ' '.join(args.content)))
+      self.stdout.write('<{0}>{1}</{0}>'.format(args.tag, ' '.join(args.content)))
       self.stdout.write('\n')
 
 The ``help tag`` command displays:
 
 .. code-block:: none
 
-   create a html tag
    usage: tag [-h] tag content [content ...]
 
+   create a html tag
+
    positional arguments:
      tag         tag
      content     content to surround with tag
@@ -85,14 +86,15 @@ The ``help tag`` command displays:
      -h, --help  show this help message and exit
 
 
-If you would prefer the short description of your command to come after the usage message, leave the docstring on your method empty, but supply a ``description`` variable to the argument parser::
+If you would prefer you can set the ``description`` while instantiating the ``argparse.ArgumentParser`` and leave the
+docstring on your method empty::
 
    argparser = argparse.ArgumentParser(description='create an html tag')
-   argparser.add_argument('tag', nargs=1, help='tag')
+   argparser.add_argument('tag', help='tag')
    argparser.add_argument('content', nargs='+', help='content to surround with tag')
    @with_argument_parser(argparser)
    def do_tag(self, args):
-      self.stdout.write('<{0}>{1}</{0}>'.format(args.tag[0], ' '.join(args.content)))
+      self.stdout.write('<{0}>{1}</{0}>'.format(args.tag, ' '.join(args.content)))
       self.stdout.write('\n')
 
 Now when the user enters ``help tag`` they see:
@@ -117,11 +119,11 @@ To add additional text to the end of the generated help message, use the ``epilo
       description='create an html tag',
       epilog='This command can not generate tags with no content, like <br/>.'
    )
-   argparser.add_argument('tag', nargs=1, help='tag')
+   argparser.add_argument('tag', help='tag')
    argparser.add_argument('content', nargs='+', help='content to surround with tag')
    @with_argument_parser(argparser)
    def do_tag(self, args):
-      self.stdout.write('<{0}>{1}</{0}>'.format(args.tag[0], ' '.join(args.content)))
+      self.stdout.write('<{0}>{1}</{0}>'.format(args.tag, ' '.join(args.content)))
       self.stdout.write('\n')
 
 Which yields:

examples/argparse_example.py

@@ -65,13 +65,13 @@ def do_speak(self, args):
     do_orate = do_speak  # another synonym, but this one takes multi-line input
 
     tag_parser = argparse.ArgumentParser()
-    tag_parser.add_argument('tag', nargs=1, help='tag')
+    tag_parser.add_argument('tag', help='tag')
     tag_parser.add_argument('content', nargs='+', help='content to surround with tag')
 
     @with_argument_parser(tag_parser)
     def do_tag(self, args):
         """create a html tag"""
-        self.poutput('<{0}>{1}</{0}>'.format(args.tag[0], ' '.join(args.content)))
+        self.poutput('<{0}>{1}</{0}>'.format(args.tag, ' '.join(args.content)))
 
 
     @with_argument_list

examples/pirate.py

@@ -76,15 +76,15 @@ def do_sing(self, arg):
     yo_parser = argparse.ArgumentParser()
     yo_parser.add_argument('--ho', type=int, default=2, help="How often to chant 'ho'")
     yo_parser.add_argument('-c', '--commas', action='store_true', help='Intersperse commas')
-    yo_parser.add_argument('beverage', nargs=1, help='beverage to drink with the chant')
+    yo_parser.add_argument('beverage', help='beverage to drink with the chant')
 
     @with_argument_parser(yo_parser)
     def do_yo(self, args):
         """Compose a yo-ho-ho type chant with flexible options."""
         chant = ['yo'] + ['ho'] * args.ho
         separator = ', ' if args.commas else ' '
         chant = separator.join(chant)
-        print('{0} and a bottle of {1}'.format(chant, args.beverage[0]))
+        print('{0} and a bottle of {1}'.format(chant, args.beverage))
 
 
 if __name__ == '__main__':

tests/test_argparse.py

@@ -37,12 +37,12 @@ def do_say(self, args):
             self.stdout.write('\n')
 
     tag_parser = argparse.ArgumentParser(description='create a html tag')
-    tag_parser.add_argument('tag', nargs=1, help='tag')
+    tag_parser.add_argument('tag', help='tag')
     tag_parser.add_argument('content', nargs='+', help='content to surround with tag')
 
     @cmd2.with_argument_parser(tag_parser)
     def do_tag(self, args):
-        self.stdout.write('<{0}>{1}</{0}>'.format(args.tag[0], ' '.join(args.content)))
+        self.stdout.write('<{0}>{1}</{0}>'.format(args.tag, ' '.join(args.content)))
         self.stdout.write('\n')
 
     @cmd2.with_argument_list