Merge pull request #901 from python-cmd2/api_docs_cleanup

Address comments from PR #899

12 files changed, 163 insertions, 57 deletions

diff --git a/cmd2/ansi.py b/cmd2/ansi.py
index 27c9e87a..ceb135ec 100644
--- a/cmd2/ansi.py
+++ b/cmd2/ansi.py
@@ -18,29 +18,29 @@ colorama.init(strip=False)
 # Values for allow_style setting
 STYLE_NEVER = 'Never'
 """
-Constant for ``cmd2.ansi.allow_style`` to indicate ANSI sequences
-should be removed from all output.
+Constant for ``cmd2.ansi.allow_style`` to indicate ANSI style sequences should
+be removed from all output.
 """
 STYLE_TERMINAL = 'Terminal'
 """
-Constant for ``cmd2.ansi.allow_style`` to indicate ANSI sequences
+Constant for ``cmd2.ansi.allow_style`` to indicate ANSI style sequences
 should be removed if the output is not going to the terminal.
 """
 STYLE_ALWAYS = 'Always'
 """
-Constant for ``cmd2.ansi.allow_style`` to indicate ANSI sequences
-should alwyas be output.
+Constant for ``cmd2.ansi.allow_style`` to indicate ANSI style sequences should
+always be output.
 """
 
-# Controls when ANSI style style sequences are allowed in output
+# Controls when ANSI style sequences are allowed in output
 allow_style = STYLE_TERMINAL
 """When using outside of a cmd2 app, set this variable to one of:
 
-- ``STYLE_NEVER`` - remove ANSI sequences from all output
-- ``STYLE_TERMINAL`` - remove ANSI sequences if the output is not going to the terminal
-- ``STYLE_ALWAYS`` - always output ANSI sequences
+- ``STYLE_NEVER`` - remove ANSI style sequences from all output
+- ``STYLE_TERMINAL`` - remove ANSI style sequences if the output is not going to the terminal
+- ``STYLE_ALWAYS`` - always output ANSI style sequences
 
-to control the output of ANSI sequences by methods in this module.
+to control the output of ANSI style sequences by methods in this module.
 
 The default is ``STYLE_TERMINAL``.
 """
diff --git a/cmd2/argparse_custom.py b/cmd2/argparse_custom.py
index 02e23f17..d6833673 100644
--- a/cmd2/argparse_custom.py
+++ b/cmd2/argparse_custom.py
@@ -92,7 +92,7 @@ path_complete, delimiter_complete)
 
     Example::
 
-        # this adds file-path completion to an argument
+        # This adds file-path completion to an argument
         parser.add_argument('-o', '--options', completer_method=cmd2.Cmd.path_complete)
 
 
@@ -101,7 +101,7 @@ path_complete, delimiter_complete)
 
     Example::
 
-        # this says to call path_complete with a preset value for its path_filter argument.
+        # This says to call path_complete with a preset value for its path_filter argument
         completer_method = functools.partial(path_complete,
                                              path_filter=lambda path: os.path.isdir(path))
         parser.add_argument('-o', '--options', choices_method=completer_method)
diff --git a/cmd2/cmd2.py b/cmd2/cmd2.py
index b2d745ac..7bee1b6a 100644
--- a/cmd2/cmd2.py
+++ b/cmd2/cmd2.py
@@ -406,7 +406,7 @@ class Cmd(cmd.Cmd):
             raise KeyError(name + " is not a settable parameter")
 
     def _build_settables(self):
-        """Construct the default settings"""
+        """Add default settables"""
         self.add_settable(Settable('allow_style', str,
                                    'Allow ANSI text style sequences in output (valid values: '
                                    '{}, {}, {})'.format(ansi.STYLE_TERMINAL,
@@ -2014,7 +2014,14 @@ class Cmd(cmd.Cmd):
     def cmd_func(self, command: str) -> Optional[Callable]:
         """
         Get the function for a command
+
         :param command: the name of the command
+
+        :Example:
+
+        >>> helpfunc = self.cmd_func('help')
+
+        helpfunc now contains a reference to the ``do_help`` method
         """
         func_name = self._cmd_func_name(command)
         if func_name:
diff --git a/cmd2/decorators.py b/cmd2/decorators.py
index e9aff0eb..2c78134c 100644
--- a/cmd2/decorators.py
+++ b/cmd2/decorators.py
@@ -1,5 +1,5 @@
 # coding=utf-8
-"""Decorators for cmd2 commands"""
+"""Decorators for ``cmd2`` commands"""
 import argparse
 from typing import Callable, List, Optional, Union
 
@@ -44,9 +44,9 @@ def with_argument_list(*args: List[Callable], preserve_quotes: bool = False) ->
     :Example:
 
     >>> class MyApp(cmd2.Cmd):
-    >>>   @cmd2.with_argument_list
-    >>>   def do_echo(self, arglist):
-    >>>     self.poutput(' '.join(arglist)
+    >>>     @cmd2.with_argument_list
+    >>>     def do_echo(self, arglist):
+    >>>         self.poutput(' '.join(arglist)
     """
     import functools
 
@@ -112,6 +112,20 @@ def with_argparser_and_unknown_args(parser: argparse.ArgumentParser, *,
              of unknown argument strings. A member called ``__statement__`` is added to the
              ``Namespace`` to provide command functions access to the :class:`cmd2.Statement`
              object. This can be useful if the command function needs to know the command line.
+
+    :Example:
+
+    >>> parser = argparse.ArgumentParser()
+    >>> parser.add_argument('-p', '--piglatin', action='store_true', help='atinLay')
+    >>> parser.add_argument('-s', '--shout', action='store_true', help='N00B EMULATION MODE')
+    >>> parser.add_argument('-r', '--repeat', type=int, help='output [n] times')
+    >>>
+    >>> class MyApp(cmd2.Cmd):
+    >>>     @cmd2.with_argparser_and_unknown_args(parser)
+    >>>     def do_argprint(self, args, unknown):
+    >>>         "Print the options and argument list this options command was called with."
+    >>>         self.poutput('args: {!r}'.format(args))
+    >>>         self.poutput('unknowns: {}'.format(unknown))
     """
     import functools
 
@@ -170,6 +184,20 @@ def with_argparser(parser: argparse.ArgumentParser, *,
     :return: function that gets passed the argparse-parsed args in a Namespace
              A member called __statement__ is added to the Namespace to provide command functions access to the
              Statement object. This can be useful if the command function needs to know the command line.
+
+    :Example:
+
+    >>> parser = argparse.ArgumentParser()
+    >>> parser.add_argument('-p', '--piglatin', action='store_true', help='atinLay')
+    >>> parser.add_argument('-s', '--shout', action='store_true', help='N00B EMULATION MODE')
+    >>> parser.add_argument('-r', '--repeat', type=int, help='output [n] times')
+    >>> parser.add_argument('words', nargs='+', help='words to print')
+    >>>
+    >>> class MyApp(cmd2.Cmd):
+    >>>     @cmd2.with_argparser(parser, preserve_quotes=True)
+    >>>     def do_argprint(self, args):
+    >>>         "Print the options and argument list this options command was called with."
+    >>>         self.poutput('args: {!r}'.format(args))
     """
     import functools
 
diff --git a/docs/api/cmd.rst b/docs/api/cmd.rst
index 3fcd3352..dd3d3abe 100644
--- a/docs/api/cmd.rst
+++ b/docs/api/cmd.rst
@@ -52,7 +52,7 @@ cmd2.Cmd
         A record of previously entered commands.
 
         This attribute is an instance of :class:`cmd2.history.History`, and
-        each command is an instance of :class:`cmd2.history.HistoryItem`.
+        each command is an instance of :class:`cmd2.Statement`.
 
     .. attribute:: statement_parser
 
diff --git a/docs/api/history.rst b/docs/api/history.rst
index 3a3ae2c4..5658238d 100644
--- a/docs/api/history.rst
+++ b/docs/api/history.rst
@@ -1,6 +1,9 @@
 cmd2.history
 ===============
 
+Classes for storing the history of previously entered commands.
+
+
 .. autoclass:: cmd2.history.History
     :members:
 
diff --git a/docs/api/index.rst b/docs/api/index.rst
index d5fc013b..aa3371b9 100644
--- a/docs/api/index.rst
+++ b/docs/api/index.rst
@@ -12,19 +12,42 @@ If a release of this library changes any of the items documented here, the
 version number will be incremented according to the `Semantic Version
 Specification <https://semver.org>`_.
 
-This documentation is for version |version| of ``cmd2``.
+This documentation is for ``cmd2`` version |version|.
 
 .. toctree::
    :maxdepth: 1
+   :hidden:
 
    cmd
-   parsing
    decorators
-   history
+   parsing
    argparse_completer
    argparse_custom
    ansi
    utils
+   history
    plugin
    py_bridge
    constants
+
+**Modules**
+
+- :ref:`api/cmd:cmd2.Cmd` - functions and attributes of the main
+  class in this library
+- :ref:`api/decorators:cmd2.decorators` - decorators for ``cmd2``
+  commands
+- :ref:`api/parsing:cmd2.parsing` - classes for parsing and storing
+  user input
+- :ref:`api/argparse_completer:cmd2.argparse_completer` - classes for
+  ``argparse``-based tab completion
+- :ref:`api/argparse_custom:cmd2.argparse_custom` - classes and functions
+  for extending ``argparse``
+- :ref:`api/ansi:cmd2.ansi` - convenience classes and functions for generating
+  ANSI escape sequences to style text in the terminal
+- :ref:`api/utils:cmd2.utils` - various utility classes and functions
+- :ref:`api/history:cmd2.history` - classes for storing the history
+  of previously entered commands
+- :ref:`api/plugin:cmd2.plugin` - data classes for hook methods
+- :ref:`api/py_bridge:cmd2.py_bridge` - classes for bridging calls from the
+  embedded python environment to the host app
+- :ref:`api/constants:cmd2.constants` - just like it says on the tin
diff --git a/docs/api/parsing.rst b/docs/api/parsing.rst
index c79c8f6b..fa726700 100644
--- a/docs/api/parsing.rst
+++ b/docs/api/parsing.rst
@@ -1,6 +1,15 @@
 cmd2.parsing
 ===============
 
+Classes for parsing and storing user input.
+
+
+.. autoclass:: cmd2.parsing.StatementParser
+    :members:
+
+    .. automethod:: __init__
+
+
 .. autoclass:: cmd2.Statement
     :members:
 
@@ -67,9 +76,3 @@ cmd2.parsing
 
       If output was redirected by the user, this contains the requested destination with
       quotes preserved.
-
-
-.. autoclass:: cmd2.parsing.StatementParser
-    :members:
-
-    .. automethod:: __init__
diff --git a/docs/api/utils.rst b/docs/api/utils.rst
index 2ae5987b..8121fea8 100644
--- a/docs/api/utils.rst
+++ b/docs/api/utils.rst
@@ -42,12 +42,6 @@ Tab Completion
 .. autoclass:: cmd2.utils.CompletionError
     :members:
 
-.. autofunction:: cmd2.utils.remove_duplicates
-
-.. autofunction:: cmd2.utils.alphabetical_sort
-
-.. autofunction:: cmd2.utils.natural_sort
-
 .. autofunction:: cmd2.utils.basic_complete
 
 
@@ -76,3 +70,9 @@ Miscellaneous
 .. autofunction:: cmd2.utils.namedtuple_with_defaults
 
 .. autofunction:: cmd2.utils.categorize
+
+.. autofunction:: cmd2.utils.remove_duplicates
+
+.. autofunction:: cmd2.utils.alphabetical_sort
+
+.. autofunction:: cmd2.utils.natural_sort
diff --git a/docs/doc_conventions.rst b/docs/doc_conventions.rst
index c37a4825..6adad4c9 100644
--- a/docs/doc_conventions.rst
+++ b/docs/doc_conventions.rst
@@ -159,6 +159,21 @@ comment instead of just #), or in a docstring after the definition. This
 project has standardized on the docstring after the definition approach. Do not
 use the specially formatted comment approach.
 
+When using the Sphix ``autoclass`` directive, it must be preceded by two blank
+lines like so:
+
+.. code-block:: rst
+
+    Classes for storing the history of previously entered commands.
+
+
+    .. autoclass:: cmd2.history.History
+        :members:
+
+
+    .. autoclass:: cmd2.history.HistoryItem
+        :members:
+
 
 Links to API Reference
 ----------------------
diff --git a/docs/examples/alternate_event_loops.rst b/docs/examples/alternate_event_loops.rst
index 41e27369..b0ee7f8e 100644
--- a/docs/examples/alternate_event_loops.rst
+++ b/docs/examples/alternate_event_loops.rst
@@ -46,26 +46,27 @@ the main loop for the program by using code like the following::
 
         app.postloop()
 
-The **runcmds_plus_hooks()** method is a convenience method to run multiple
-commands via **onecmd_plus_hooks()**.
+The :meth:`~cmd2.Cmd.runcmds_plus_hooks()` method runs multiple commands via
+:meth:`~cmd2.Cmd.onecmd_plus_hooks`.
 
-The **onecmd_plus_hooks()** method will do the following to execute a single
-``cmd2`` command in a normal fashion:
+The :meth:`~cmd2.Cmd.onecmd_plus_hooks()` method will do the following to
+execute a single command in a normal fashion:
 
-#. Parse user input into `Statement` object
-#. Call methods registered with `register_postparsing_hook()`
+#. Parse user input into a :class:`~cmd2.Statement` object
+#. Call methods registered with :meth:`~cmd2.Cmd.register_postparsing_hook()`
 #. Redirect output, if user asked for it and it's allowed
 #. Start timer
-#. Call methods registered with `register_precmd_hook()`
-#. Call `precmd()` - for backwards compatibility with ``cmd.Cmd``
-#. Add statement to history
+#. Call methods registered with :meth:`~cmd2.Cmd.register_precmd_hook`
+#. Call :meth:`~cmd2.Cmd.precmd` - for backwards compatibility with ``cmd.Cmd``
+#. Add statement to :ref:`features/history:History`
 #. Call `do_command` method
-#. Call methods registered with `register_postcmd_hook()`
-#. Call `postcmd(stop, statement)` - for backwards compatibility with
+#. Call methods registered with :meth:`~cmd2.Cmd.register_postcmd_hook()`
+#. Call :meth:`~cmd2.Cmd.postcmd` - for backwards compatibility with
    ``cmd.Cmd``
 #. Stop timer and display the elapsed time
 #. Stop redirecting output if it was redirected
-#. Call methods registered with `register_cmdfinalization_hook()`
+#. Call methods registered with
+   :meth:`~cmd2.Cmd.register_cmdfinalization_hook()`
 
 Running in this fashion enables the ability to integrate with an external event
 loop.  However, how to integrate with any specific event loop is beyond the
@@ -75,8 +76,3 @@ with several disadvantages, including:
 * Requires the developer to write more code
 * Does not support transcript testing
 * Does not allow commands at invocation via command-line arguments
-
-Here is a little more info on ``runcmds_plus_hooks``:
-
-.. automethod:: cmd2.Cmd.runcmds_plus_hooks
-    :noindex:
diff --git a/docs/features/history.rst b/docs/features/history.rst
index 56c74ed7..c84b854c 100644
--- a/docs/features/history.rst
+++ b/docs/features/history.rst
@@ -4,14 +4,46 @@ History
 For Developers
 --------------
 
-- Describe how ``cmd2`` tracks history
-- how persistent history works
-- differences in history and bash shell history (we only store valid commands
-  in history)
-- reference the public code structures we use to store history
+The ``cmd`` module from the Python standard library includes ``readline``
+history.
+
+:class:`cmd2.Cmd` offers the same ``readline`` capabilities, but also maintains
+it's own data structures for the history of all commands entered by the user.
+When the class is initialized, it creates an instance of the
+:class:`cmd2.history.History` class (which is a subclass of ``list``) as
+:data:`cmd2.Cmd.history`.
+
+Each time a command is executed (this gets
+complex, see :ref:`features/hooks:Command Processing Loop` for exactly when)
+the parsed :class:`cmd2.Statement` is appended to :data:`cmd2.Cmd.history`.
 
 ``cmd2`` adds the option of making this history persistent via optional
-arguments to :meth:`cmd2.Cmd.__init__`.
+arguments to :meth:`cmd2.Cmd.__init__`. If you pass a filename in the
+``persistent_history_file`` argument, the contents of :data:`cmd2.Cmd.history`
+will be pickled into that history file. We chose to use pickle instead of plain
+text so that we can save the results of parsing all the commands.
+
+.. note::
+
+    ``readline`` saves everything you type, whether it is a valid command or
+    not. ``cmd2`` only saves input to internal history if the command parses
+    successfully and is a valid command. This design choice was intentional,
+    because the contents of history can be saved to a file as a script, or can
+    be re-run. Not saving invalid input reduces unintentional errors when doing
+    so.
+
+    However, this design choice causes an inconsistency between the
+    ``readline`` history and the ``cmd2`` history when you enter an invalid
+    command: it is saved to the ``readline`` history, but not to the ``cmd2``
+    history.
+
+The :data:`cmd2.Cmd.history` attribute, the :class:`cmd2.history.History`
+class, and the :class:`cmd2.history.HistoryItem` class are all part of the
+public API for :class:`cmd2.Cmd`. You could use these classes to implement
+write your own ``history`` command (see below for documentation on how the
+included ``history`` command works). If you don't like pickled history, you
+could implement your own mechanism for saving and loading history from a plain
+text file.
 
 
 For Users
@@ -236,4 +268,3 @@ If the entered command had no expansion, it is displayed as usual. However, if
 there is some change as the result of expanding macros and aliases, then the
 entered command is displayed with the number, and the expanded command is
 displayed with the number followed by an ``x``.
-