Merge pull request #899 from python-cmd2/api_docs

API documentation

13 files changed, 316 insertions, 84 deletions

diff --git a/docs/api/argparse_completer.rst b/docs/api/argparse_completer.rst
new file mode 100644
index 00000000..0e277582
--- /dev/null
+++ b/docs/api/argparse_completer.rst
@@ -0,0 +1,5 @@
+cmd2.argparse_completer
+=======================
+
+.. automodule:: cmd2.argparse_completer
+    :members:
diff --git a/docs/api/argparse_custom.rst b/docs/api/argparse_custom.rst
new file mode 100644
index 00000000..bdb53e1a
--- /dev/null
+++ b/docs/api/argparse_custom.rst
@@ -0,0 +1,5 @@
+cmd2.argparse_custom
+====================
+
+.. automodule:: cmd2.argparse_custom
+    :members:
diff --git a/docs/api/cmd.rst b/docs/api/cmd.rst
index 213a14ec..3fcd3352 100644
--- a/docs/api/cmd.rst
+++ b/docs/api/cmd.rst
@@ -24,13 +24,42 @@ cmd2.Cmd
 
     .. attribute:: prompt
 
-      The prompt issued to solicit input.
-      Default: ``(Cmd)``.
+      The prompt issued to solicit input. The default value is ``(Cmd)``.
+      See :ref:`features/prompt:Prompt` for more information.
+
+    .. attribute:: continuation_prompt
+
+      The prompt issued to solicit input for the 2nd and subsequent lines
+      of a :ref:`multiline command <features/multiline_commands:Multiline Commands>`
+
+    .. attribute:: echo
+
+      If ``True``, output the prompt and user input before executing the command.
+      When redirecting a series of commands to an output file, this allows you to
+      see the command in the output.
 
     .. attribute:: settable
 
-        This dictionary contains the name and description of all settings available to users.
+        This dictionary contains the name and description of all settings
+        available to users.
 
         Users use the :ref:`features/builtin_commands:set` command to view and
         modify settings. Settings are stored in instance attributes with the
         same name as the setting.
+
+    .. attribute:: history
+
+        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`.
+
+    .. attribute:: statement_parser
+
+        An instance of :class:`cmd2.parsing.StatementParser` initialized and
+        configured appropriately for parsing user input.
+
+    .. attribute:: intro
+
+        Set an introduction message which is displayed to the user before
+        the :ref:`features/hooks:Command Processing Loop` begins.
diff --git a/docs/api/constants.rst b/docs/api/constants.rst
new file mode 100644
index 00000000..b48ba462
--- /dev/null
+++ b/docs/api/constants.rst
@@ -0,0 +1,29 @@
+cmd2.constants
+==============
+
+.. automodule:: cmd2.constants
+
+  .. data:: DEFAULT_SHORTCUTS
+
+    If you do not supply shortcuts to :meth:`cmd2.Cmd.__init__`, the shortcuts
+    defined here will be used instead.
+
+
+  .. data:: COMMAND_NAME
+
+    Used by :meth:`cmd2.Cmd.disable_command` and
+    :meth:`cmd2.Cmd.disable_category`. Those methods allow you to selectively
+    disable single commands or an entire category of commands. Should you want
+    to include the name of the command in the error message displayed to the
+    user when they try and run a disabled command, you can include this
+    constant in the message where you would like the name of the command to
+    appear. ``cmd2`` will replace this constant with the name of the command
+    the user tried to run before displaying the error message.
+
+    This constant is imported into the package namespace; the preferred syntax
+    to import and reference it is::
+
+        import cmd2
+        errmsg = "The {} command is currently disabled.".format(cmd2.COMMAND_NAME)
+
+    See ``src/examples/help_categories.py`` for an example.
diff --git a/docs/api/decorators.rst b/docs/api/decorators.rst
index 12ab62fa..c78dcc66 100644
--- a/docs/api/decorators.rst
+++ b/docs/api/decorators.rst
@@ -1,10 +1,5 @@
-Decorators
-==========
+cmd2.decorators
+===============
 
-.. autofunction:: cmd2.decorators.with_argparser
-
-.. autofunction:: cmd2.decorators.with_argparser_and_unknown_args
-
-.. autofunction:: cmd2.decorators.with_argument_list
-
-.. autofunction:: cmd2.decorators.with_category
+.. automodule:: cmd2.decorators
+    :members:
diff --git a/docs/api/history.rst b/docs/api/history.rst
new file mode 100644
index 00000000..3a3ae2c4
--- /dev/null
+++ b/docs/api/history.rst
@@ -0,0 +1,17 @@
+cmd2.history
+===============
+
+.. autoclass:: cmd2.history.History
+    :members:
+
+
+.. autoclass:: cmd2.history.HistoryItem
+    :members:
+
+    .. attribute:: statement
+
+      The :class:`~cmd2.Statement` object parsed from user input
+
+    .. attribute:: idx
+
+      The 1-based index of this statement in the history list
diff --git a/docs/api/index.rst b/docs/api/index.rst
index 346fc274..d5fc013b 100644
--- a/docs/api/index.rst
+++ b/docs/api/index.rst
@@ -1,11 +1,30 @@
 API Reference
 =============
 
+These pages document the public API for ``cmd2``. If a method, class, function,
+attribute, or constant is not documented here, consider it private and subject
+to change. There are many classes, methods, functions, and constants in the
+source code which do not begin with an underscore but are not documented here.
+When looking at the source code for this library, you can not safely assume
+that because something doesn't start with an underscore, it is a public API.
+
+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``.
+
 .. toctree::
    :maxdepth: 1
 
    cmd
+   parsing
    decorators
+   history
+   argparse_completer
+   argparse_custom
    ansi
-   utility_classes
-   utility_functions
+   utils
+   plugin
+   py_bridge
+   constants
diff --git a/docs/api/parsing.rst b/docs/api/parsing.rst
new file mode 100644
index 00000000..c79c8f6b
--- /dev/null
+++ b/docs/api/parsing.rst
@@ -0,0 +1,75 @@
+cmd2.parsing
+===============
+
+.. autoclass:: cmd2.Statement
+    :members:
+
+    .. attribute:: command
+
+      The name of the command after shortcuts and macros have been expanded
+
+    .. attribute:: args
+
+      The arguments to the command as a string with spaces between the words,
+      excluding output redirection and command terminators. If the user used
+      quotes in their input, they remain here, and you will have to handle them
+      on your own.
+
+    .. attribute:: arg_list
+
+      The arguments to the command as a list, excluding output
+      redirection and command terminators. Each argument is represented as an
+      element in the list. Quoted arguments remain quoted. If you want to
+      remove the quotes, use :func:`cmd2.utils.strip_quotes` or use
+      ``argv[1:]``
+
+    .. attribute:: raw
+
+      If you want full access to exactly what the user typed at the input
+      prompt you can get it, but you'll have to parse it on your own,
+      including:
+
+        - shortcuts and aliases
+        - quoted commands and arguments
+        - output redirection
+        - multi-line command terminator handling
+
+      If you use multiline commands, all the input will be passed to you in
+      this string, but there will be embedded newlines where the user hit
+      return to continue the command on the next line.
+
+    .. attribute:: multiline_command
+
+      If the command is a multi-line command, the name of the command will be
+      in this attribute. Otherwise, it will be an empty string.
+
+    .. attribute:: terminator
+
+      If the command is a multi-line command, this attribute contains the
+      termination character entered by the user to signal the end of input
+
+    .. attribute:: suffix
+
+      Any characters present between the input terminator and the output
+      redirection tokens.
+
+    .. attribute:: pipe_to
+
+      If the user piped the output to a shell command, this attribute contains
+      the entire shell command as a string. Otherwise it is an empty string.
+
+    .. attribute:: output
+
+      If output was redirected by the user, this contains the redirection
+      token, i.e. ``>>``.
+
+    .. attribute:: output_to
+
+      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/plugin.rst b/docs/api/plugin.rst
new file mode 100644
index 00000000..4e554b33
--- /dev/null
+++ b/docs/api/plugin.rst
@@ -0,0 +1,45 @@
+cmd2.plugin
+===========
+
+.. autoclass:: cmd2.plugin.PostparsingData
+    :members:
+
+    .. attribute:: stop
+
+      Request the command loop terminate by setting ``True``
+
+    .. attribute:: statement
+
+      The :class:`~cmd2.Statement` object parsed from user input
+
+
+.. autoclass:: cmd2.plugin.PrecommandData
+    :members:
+
+    .. attribute:: statement
+
+      The :class:`~cmd2.Statement` object parsed from user input
+
+
+.. autoclass:: cmd2.plugin.PostcommandData
+    :members:
+
+    .. attribute:: stop
+
+      Request the command loop terminate by setting ``True``
+
+    .. attribute:: statement
+
+      The :class:`~cmd2.Statement` object parsed from user input
+
+
+.. autoclass:: cmd2.plugin.CommandFinalizationData
+    :members:
+
+    .. attribute:: stop
+
+      Request the command loop terminate by setting ``True``
+
+    .. attribute:: statement
+
+      The :class:`~cmd2.Statement` object parsed from user input
diff --git a/docs/api/py_bridge.rst b/docs/api/py_bridge.rst
new file mode 100644
index 00000000..28a70b59
--- /dev/null
+++ b/docs/api/py_bridge.rst
@@ -0,0 +1,5 @@
+cmd2.py_bridge
+==============
+
+.. automodule:: cmd2.py_bridge
+    :members:
diff --git a/docs/api/utility_classes.rst b/docs/api/utility_classes.rst
deleted file mode 100644
index 2ee92ced..00000000
--- a/docs/api/utility_classes.rst
+++ /dev/null
@@ -1,16 +0,0 @@
-Utility Classes
-===============
-
-.. autoclass:: cmd2.utils.Settable
-
-    .. automethod:: __init__
-
-.. autoclass:: cmd2.utils.StdSim
-
-.. autoclass:: cmd2.utils.ByteBuf
-
-.. autoclass:: cmd2.utils.ProcReader
-
-.. autoclass:: cmd2.utils.ContextFlag
-
-.. autoclass:: cmd2.utils.RedirectionSavedState
diff --git a/docs/api/utility_functions.rst b/docs/api/utility_functions.rst
deleted file mode 100644
index b348ac1c..00000000
--- a/docs/api/utility_functions.rst
+++ /dev/null
@@ -1,54 +0,0 @@
-Utility Functions
-=================
-
-.. autofunction:: cmd2.utils.is_quoted
-
-.. autofunction:: cmd2.utils.quote_string_if_needed
-
-.. autofunction:: cmd2.utils.strip_quotes
-
-.. autofunction:: cmd2.utils.categorize
-
-.. autofunction:: cmd2.utils.align_text
-
-.. autofunction:: cmd2.utils.align_left
-
-.. autofunction:: cmd2.utils.align_center
-
-.. autofunction:: cmd2.utils.align_right
-
-.. autofunction:: cmd2.utils.truncate_line
-
-.. autofunction:: cmd2.utils.strip_quotes
-
-.. autofunction:: cmd2.utils.namedtuple_with_defaults
-
-.. autofunction:: cmd2.utils.which
-
-.. autofunction:: cmd2.utils.is_text_file
-
-.. autofunction:: cmd2.utils.remove_duplicates
-
-.. autofunction:: cmd2.utils.norm_fold
-
-.. autofunction:: cmd2.utils.try_int_or_force_to_lower_case
-
-.. autofunction:: cmd2.utils.alphabetical_sort
-
-.. autofunction:: cmd2.utils.unquote_specific_tokens
-
-.. autofunction:: cmd2.utils.natural_sort
-
-.. autofunction:: cmd2.utils.natural_keys
-
-.. autofunction:: cmd2.utils.expand_user_in_tokens
-
-.. autofunction:: cmd2.utils.expand_user
-
-.. autofunction:: cmd2.utils.find_editor
-
-.. autofunction:: cmd2.utils.get_exes_in_path
-
-.. autofunction:: cmd2.utils.files_from_glob_patterns
-
-.. autofunction:: cmd2.utils.files_from_glob_pattern
diff --git a/docs/api/utils.rst b/docs/api/utils.rst
new file mode 100644
index 00000000..2ae5987b
--- /dev/null
+++ b/docs/api/utils.rst
@@ -0,0 +1,78 @@
+cmd2.utils
+==========
+
+
+Settings
+--------
+
+.. autoclass:: cmd2.utils.Settable
+    :members:
+
+    .. automethod:: __init__
+
+
+Quote Handling
+--------------
+
+.. autofunction:: cmd2.utils.is_quoted
+
+.. autofunction:: cmd2.utils.quote_string
+
+.. autofunction:: cmd2.utils.quote_string_if_needed
+
+.. autofunction:: cmd2.utils.strip_quotes
+
+
+IO Handling
+-----------
+
+.. autoclass:: cmd2.utils.StdSim
+    :members:
+
+.. autoclass:: cmd2.utils.ByteBuf
+    :members:
+
+.. autoclass:: cmd2.utils.ProcReader
+    :members:
+
+
+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
+
+
+Text Alignment
+--------------
+
+.. autoclass:: cmd2.utils.TextAlignment
+    :members:
+
+.. autofunction:: cmd2.utils.align_text
+
+.. autofunction:: cmd2.utils.align_left
+
+.. autofunction:: cmd2.utils.align_right
+
+.. autofunction:: cmd2.utils.align_center
+
+.. autofunction:: cmd2.utils.truncate_line
+
+
+Miscellaneous
+-------------
+
+.. autofunction:: cmd2.utils.str_to_bool
+
+.. autofunction:: cmd2.utils.namedtuple_with_defaults
+
+.. autofunction:: cmd2.utils.categorize