Merge branch 'master' into color_autocomplete

tleonhardt · tleonhardt · commit 138c28d18cee · 2020-02-06T23:40:18.000-05:00
diff --git a/docs/api/cmd.rst b/docs/api/cmd.rst
@@ -1,9 +1,11 @@
 cmd2.Cmd
 ========
 
-.. autoclass:: cmd2.cmd2.Cmd
+.. autoclass:: cmd2.Cmd
     :members:
 
+    .. automethod:: __init__
+
     .. attribute:: help_error
 
       The error message displayed to the user when they request help for a
diff --git a/docs/api/decorators.rst b/docs/api/decorators.rst
@@ -1,10 +1,10 @@
 Decorators
 ==========
 
-.. autofunction:: cmd2.decorators.with_category
-
-.. autofunction:: cmd2.decorators.with_argument_list
+.. autofunction:: cmd2.decorators.with_argparser
 
 .. autofunction:: cmd2.decorators.with_argparser_and_unknown_args
 
-.. autofunction:: cmd2.decorators.with_argparser
+.. autofunction:: cmd2.decorators.with_argument_list
+
+.. autofunction:: cmd2.decorators.with_category
diff --git a/docs/api/exceptions.rst b/docs/api/exceptions.rst
@@ -1,6 +1,4 @@
 Exceptions
 ==========
 
-.. autoexception:: cmd2.cmd2.EmbeddedConsoleExit
-
-.. autoexception:: cmd2.cmd2.EmptyStatement
+.. autoexception:: cmd2.EmptyStatement
diff --git a/docs/doc_conventions.rst b/docs/doc_conventions.rst
@@ -167,28 +167,20 @@ To reference a method or function, use one of the following approaches:
 
 1. Reference the full dotted path of the method::
 
-     The :meth:`cmd2.cmd2.Cmd.poutput` method is similar to the Python built-in
+     The :meth:`cmd2.Cmd.poutput` method is similar to the Python built-in
      print function.
 
-Which renders as: The :meth:`cmd2.cmd2.Cmd.poutput` method is similar to the
+Which renders as: The :meth:`cmd2.Cmd.poutput` method is similar to the
 Python built-in print function.
 
 2. Reference the full dotted path to the method, but only display the method
 name::
 
-     The :meth:`~cmd2.cmd2.Cmd.poutput` method is similar to the Python built-in print function.
+     The :meth:`~cmd2.Cmd.poutput` method is similar to the Python built-in print function.
 
-Which renders as: The :meth:`~cmd2.cmd2.Cmd.poutput` method is similar to the
+Which renders as: The :meth:`~cmd2.Cmd.poutput` method is similar to the
 Python built-in print function.
 
-3. Reference a portion of the dotted path of the method::
-
-     The :meth:`.cmd2.Cmd.poutput` method is similar to the Python built-in print
-     function.
-
-Which renders as: The :meth:`.cmd2.Cmd.poutput` method is similar to the Python
-built-in print function.
-
 Avoid either of these approaches:
 
 1. Reference just the class name without enough dotted path::
diff --git a/docs/examples/alternate_event_loops.rst b/docs/examples/alternate_event_loops.rst
@@ -5,7 +5,7 @@ Throughout this documentation we have focused on the **90%** use case, that is
 the use case we believe around **90+%** of our user base is looking for.  This
 focuses on ease of use and the best out-of-the-box experience where developers
 get the most functionality for the least amount of effort.  We are talking
-about running cmd2 applications with the ``cmdloop()`` method::
+about running ``cmd2`` applications with the ``cmdloop()`` method::
 
     from cmd2 import Cmd
     class App(Cmd):
@@ -78,5 +78,5 @@ with several disadvantages, including:
 
 Here is a little more info on ``runcmds_plus_hooks``:
 
-.. automethod:: cmd2.cmd2.Cmd.runcmds_plus_hooks
+.. automethod:: cmd2.Cmd.runcmds_plus_hooks
     :noindex:
diff --git a/docs/features/argument_processing.rst b/docs/features/argument_processing.rst
@@ -31,29 +31,21 @@ applications.
 .. _argprint: https://github.com/python-cmd2/cmd2/blob/master/examples/arg_print.py
 .. _decorator: https://github.com/python-cmd2/cmd2/blob/master/examples/decorator_example.py
 
-.. _decorators:
-
-Decorators provided by cmd2 for argument processing
----------------------------------------------------
-
 ``cmd2`` provides the following decorators for assisting with parsing arguments
 passed to commands:
 
-.. automethod:: cmd2.decorators.with_argparser
-   :noindex:
-.. automethod:: cmd2.decorators.with_argparser_and_unknown_args
-   :noindex:
-.. automethod:: cmd2.decorators.with_argument_list
-   :noindex:
+* :func:`cmd2.decorators.with_argparser`
+* :func:`cmd2.decorators.with_argparser_and_unknown_args`
+* :func:`cmd2.decorators.with_argument_list`
 
 All of these decorators accept an optional **preserve_quotes** argument which
 defaults to ``False``. Setting this argument to ``True`` is useful for cases
 where you are passing the arguments to another command which might have its own
 argument parsing.
 
 
-Using the argument parser decorator
------------------------------------
+Argument Parsing
+----------------
 
 For each command in the ``cmd2`` subclass which requires argument parsing,
 create a unique instance of ``argparse.ArgumentParser()`` which can parse the
@@ -108,8 +100,8 @@ Here's what it looks like::
 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_argparser`` decorator, the
+By default, ``cmd2`` uses the docstring of the command method when a user asks
+for help on the command. When you use the ``@with_argparser`` decorator, the
 docstring for the ``do_*`` method is used to set the description for the
 ``argparse.ArgumentParser``.
 
@@ -215,8 +207,8 @@ Which yields:
 .. _argparse: https://docs.python.org/3/library/argparse.html
 
 
-Receiving an argument list
---------------------------
+Argument List
+-------------
 
 The default behavior of ``cmd2`` is to pass the user input directly to your
 ``do_*`` methods as a string. The object passed to your method is actually a
@@ -265,7 +257,7 @@ argument list instead of a string::
             pass
 
 
-Unknown positional arguments
+Unknown Positional Arguments
 ----------------------------
 
 If you want all unknown arguments to be passed to your command as a list of
@@ -295,8 +287,8 @@ Here's what it looks like::
 
         ...
 
-Using custom argparse.Namespace
--------------------------------
+Using A Custom Namespace
+------------------------
 
 In some cases, it may be necessary to write custom ``argparse`` code that is
 dependent on state data of your application.  To support this ability while
@@ -332,7 +324,7 @@ Subcommands are supported for commands using either the ``@with_argparser`` or
 ``@with_argparser_and_unknown_args`` decorator.  The syntax for supporting them
 is based on argparse sub-parsers.
 
-You may add multiple layers of subcommands for your command. Cmd2 will
+You may add multiple layers of subcommands for your command. ``cmd2`` will
 automatically traverse and tab-complete subcommands for all commands using
 argparse.
 
diff --git a/docs/features/builtin_commands.rst b/docs/features/builtin_commands.rst
@@ -1,7 +1,7 @@
 Builtin Commands
 ================
 
-Applications which subclass :class:`cmd2.cmd2.Cmd` inherit a number of commands
+Applications which subclass :class:`cmd2.Cmd` inherit a number of commands
 which may be useful to your users. Developers can
 :ref:`features/builtin_commands:Remove Builtin Commands` if they do not want
 them to be part of the application.
@@ -130,9 +130,9 @@ This command lists available shortcuts.  See
 Remove Builtin Commands
 -----------------------
 
-Developers may not want to offer the commands builtin to :class:`cmd2.cmd2.Cmd`
+Developers may not want to offer the commands builtin to :class:`cmd2.Cmd`
 to users of their application. To remove a command you must delete the method
-implementing that command from the :class:`cmd2.cmd2.Cmd` object at runtime.
+implementing that command from the :class:`cmd2.Cmd` object at runtime.
 For example, if you wanted to remove the :ref:`features/builtin_commands:shell`
 command from your application::
 
diff --git a/docs/features/completion.rst b/docs/features/completion.rst
@@ -36,8 +36,8 @@ similar to the following to your class which inherits from ``cmd2.Cmd``::
 Tab Completion Using Argparse Decorators
 ----------------------------------------
 
-When using one the Argparse-based :ref:`decorators`, ``cmd2`` provides
-automatic tab-completion of flag names.
+When using one the Argparse-based :ref:`api/decorators:Decorators`, ``cmd2``
+provides automatic tab-completion of flag names.
 
 Tab-completion of argument values can be configured by using one of five
 parameters to ``argparse.ArgumentParser.add_argument()``
diff --git a/docs/features/embedded_python_shells.rst b/docs/features/embedded_python_shells.rst
@@ -5,12 +5,12 @@ The ``py`` command will run its arguments as a Python command.  Entered without
 arguments, it enters an interactive Python session.  The session can call
 "back" to your application through the name defined in ``self.pyscript_name``
 (defaults to ``app``).  This wrapper provides access to execute commands in
-your cmd2 application while maintaining isolation.
+your ``cmd2`` application while maintaining isolation.
 
 You may optionally enable full access to to your application by setting
 ``self_in_py`` to ``True``.  Enabling this flag adds ``self`` to the python
-session, which is a reference to your Cmd2 application. This can be useful for
-debugging your application.
+session, which is a reference to your ``cmd2`` application. This can be useful
+for debugging your application.
 
 The ``app`` object (or your custom name) provides access to application
 commands through raw commands.  For example, any application command call be
diff --git a/docs/features/generating_output.rst b/docs/features/generating_output.rst
@@ -7,34 +7,34 @@ methods::
   print("Greetings, Professor Falken.", file=self.stdout)
   self.stdout.write("Shall we play a game?\n")
 
-While you could send output directly to ``sys.stdout``, :mod:`cmd2.cmd2.Cmd`
+While you could send output directly to ``sys.stdout``, :mod:`cmd2.Cmd`
 can be initialized with a ``stdin`` and ``stdout`` variables, which it stores
 as ``self.stdin`` and ``self.stdout``. By using these variables every time you
 produce output, you can trivially change where all the output goes by changing
 how you initialize your class.
 
-:mod:`cmd2.cmd2.Cmd` extends this approach in a number of convenient ways. See
+:mod:`cmd2.Cmd` extends this approach in a number of convenient ways. See
 :ref:`features/redirection:Output Redirection And Pipes` for information on how
 users can change where the output of a command is sent. In order for those
 features to work, the output you generate must be sent to ``self.stdout``. You
 can use the methods described above, and everything will work fine.
-:mod:`cmd2.cmd2.Cmd` also includes a number of output related methods which you
+:mod:`cmd2.Cmd` also includes a number of output related methods which you
 may use to enhance the output your application produces.
 
 
 Ordinary Output
 ---------------
 
-The :meth:`~.cmd2.Cmd.poutput` method is similar to the Python
-`built-in print function <https://docs.python.org/3/library/functions.html#print>`_. :meth:`~.cmd2.Cmd.poutput` adds two
+The :meth:`~cmd2.Cmd.poutput` method is similar to the Python
+`built-in print function <https://docs.python.org/3/library/functions.html#print>`_. :meth:`~cmd2.Cmd.poutput` adds two
 conveniences:
 
   1. Since users can pipe output to a shell command, it catches
   ``BrokenPipeError`` and outputs the contents of
   ``self.broken_pipe_warning`` to ``stderr``. ``self.broken_pipe_warning``
   defaults to an empty string so this method will just swallow the exception.
   If you want to show an error message, put it in
-  ``self.broken_pipe_warning`` when you initialize :mod:`~cmd2.cmd2.Cmd`.
+  ``self.broken_pipe_warning`` when you initialize :mod:`~cmd2.Cmd`.
 
   2. It examines and honors the :ref:`features/settings:allow_style` setting.
   See :ref:`features/generating_output:Colored Output` below for more details.
diff --git a/docs/features/history.rst b/docs/features/history.rst
@@ -4,16 +4,14 @@ History
 For Developers
 --------------
 
-- Describe how cmd2 tracks history
+- 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
 
 ``cmd2`` adds the option of making this history persistent via optional
-arguments to ``cmd2.Cmd.__init__()``:
-
-.. automethod:: cmd2.cmd2.Cmd.__init__
+arguments to :meth:`cmd2.Cmd.__init__`.
 
 
 For Users
diff --git a/docs/features/hooks.rst b/docs/features/hooks.rst
@@ -1,7 +1,7 @@
 Hooks
 =====
 
-The typical way of starting a cmd2 application is as follows::
+The typical way of starting a ``cmd2`` application is as follows::
 
     import cmd2
     class App(cmd2.Cmd):
diff --git a/docs/features/initialization.rst b/docs/features/initialization.rst
@@ -79,7 +79,7 @@ useful as a superclass of a class you define yourself in order to inherit
 Certain things must be initialized within the ``__init__()`` method of your
 class derived from ``cmd2.Cmd``(all arguments to ``__init__()`` are optional):
 
-.. automethod:: cmd2.cmd2.Cmd.__init__
+.. automethod:: cmd2.Cmd.__init__
     :noindex:
 
 Cmd instance attributes
diff --git a/docs/features/misc.rst b/docs/features/misc.rst
@@ -23,7 +23,7 @@ Presents numbered options to user, as bash ``select``.
 ``app.select`` is called from within a method (not by the user directly; it is
 ``app.select``, not ``app.do_select``).
 
-.. automethod:: cmd2.cmd2.Cmd.select
+.. automethod:: cmd2.Cmd.select
     :noindex:
 
 ::
diff --git a/docs/features/os.rst b/docs/features/os.rst
@@ -149,7 +149,7 @@ single or double quotes)::
     (Cmd)
 
 Automating cmd2 apps from other CLI/CLU tools
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 While ``cmd2`` is designed to create **interactive** command-line applications
 which enter a Read-Evaluate-Print-Loop (REPL), there are a great many times
diff --git a/docs/features/packaging.rst b/docs/features/packaging.rst
@@ -1,6 +1,6 @@
 
 Packaging a cmd2 application for distribution
-=============================================
+=================================================
 
 As a general-purpose tool for building interactive command-line applications,
 ``cmd2`` is designed to be used in many ways. How you distribute your ``cmd2``
diff --git a/docs/features/settings.rst b/docs/features/settings.rst
diff --git a/docs/migrating/next_steps.rst b/docs/migrating/next_steps.rst
diff --git a/docs/overview/integrating.rst b/docs/overview/integrating.rst
