Merge pull request #875 from python-cmd2/doc_streamline

Doc streamline

Author: tleonhardt

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

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

docs/api/exceptions.rst

@@ -1,6 +1,4 @@
 Exceptions
 ==========
 
-.. autoexception:: cmd2.cmd2.EmbeddedConsoleExit
-
-.. autoexception:: cmd2.cmd2.EmptyStatement
+.. autoexception:: cmd2.EmptyStatement

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::

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:

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.
 

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::
 

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()``

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

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.