Major overhaul of documentation structure for #709

26 files changed, 406 insertions, 85 deletions

diff --git a/cmd2/utils.py b/cmd2/utils.py
index 812fa227..872c2192 100644
--- a/cmd2/utils.py
+++ b/cmd2/utils.py
@@ -18,6 +18,7 @@ from . import constants
 def is_quoted(arg: str) -> bool:
     """
     Checks if a string is quoted
+
     :param arg: the string being checked for quotes
     :return: True if a string is quoted
     """
diff --git a/docs/api/cmd.rst b/docs/api/cmd.rst
new file mode 100644
index 00000000..f9eefab2
--- /dev/null
+++ b/docs/api/cmd.rst
@@ -0,0 +1,2 @@
+cmd object
+==========
diff --git a/docs/api/decorators.rst b/docs/api/decorators.rst
new file mode 100644
index 00000000..d7bfa138
--- /dev/null
+++ b/docs/api/decorators.rst
@@ -0,0 +1,10 @@
+Decorators
+==========
+
+.. autofunction:: cmd2.cmd2.with_category
+
+.. autofunction:: cmd2.cmd2.with_argument_list
+
+.. autofunction:: cmd2.cmd2.with_argparser_and_unknown_args
+
+.. autofunction:: cmd2.cmd2.with_argparser
diff --git a/docs/api/exceptions.rst b/docs/api/exceptions.rst
new file mode 100644
index 00000000..656c4a5a
--- /dev/null
+++ b/docs/api/exceptions.rst
@@ -0,0 +1,6 @@
+Exceptions
+==========
+
+.. autoexception:: cmd2.cmd2.EmbeddedConsoleExit
+
+.. autoexception:: cmd2.cmd2.EmptyStatement
diff --git a/docs/api/utility_classes.rst b/docs/api/utility_classes.rst
new file mode 100644
index 00000000..7ed0c584
--- /dev/null
+++ b/docs/api/utility_classes.rst
@@ -0,0 +1,12 @@
+Utility Classes
+===============
+
+.. 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
new file mode 100644
index 00000000..57a720bf
--- /dev/null
+++ b/docs/api/utility_functions.rst
@@ -0,0 +1,48 @@
+Utility Functions
+=================
+
+.. autofunction:: cmd2.utils.is_quoted
+
+.. autofunction:: cmd2.utils.quote_string_if_needed
+
+.. autofunction:: cmd2.utils.strip_quotes
+
+.. autofunction:: cmd2.cmd2.categorize
+
+.. autofunction:: cmd2.utils.center_text
+
+.. autofunction:: cmd2.utils.strip_quotes
+
+.. autofunction:: cmd2.utils.namedtuple_with_defaults
+
+.. autofunction:: cmd2.utils.cast
+
+.. 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/conf.py b/docs/conf.py
index f22a117d..cc7fea2e 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -37,6 +37,7 @@ sys.path.insert(0, os.path.abspath('..'))
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = ['sphinx.ext.autodoc',
+              'sphinx.ext.autosectionlabel',
               'sphinx.ext.intersphinx',
               'sphinx.ext.doctest',
               'sphinx.ext.todo']
@@ -55,8 +56,8 @@ master_doc = 'index'
 
 # General information about the project.
 project = 'cmd2'
-copyright = '2010-2018, Catherine Devlin and Todd Leonhardt'
-author = 'Catherine Devlin and Todd Leonhardt'
+copyright = '2010-2019, Catherine Devlin and Todd Leonhardt'
+author = 'cmd2 contributors'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -85,6 +86,8 @@ pygments_style = 'sphinx'
 # If true, `todo` and `todoList` produce output, else they produce nothing.
 todo_include_todos = False
 
+# configure autosectionlabel extension
+autosectionlabel_prefix_document = True
 
 # -- Options for HTML output ---------------------------------------------------
 
diff --git a/docs/doc_conventions.rst b/docs/doc_conventions.rst
new file mode 100644
index 00000000..504c930d
--- /dev/null
+++ b/docs/doc_conventions.rst
@@ -0,0 +1,109 @@
+Documentation Conventions
+=========================
+
+Guiding Principles
+------------------
+
+Follow the `Documentation Principles
+<http://www.writethedocs.org/guide/writing/docs-principles/>`_ described by
+`Write The Docs <http://www.writethedocs.org>`_
+
+In addition:
+
+- We have gone to great lengths to retain compatibility with the standard library cmd, the documentation should make it easy for developers to understand how to move from cmd to cmd2, and what benefits that will provide
+- We should provide both descriptive and reference documentation.
+- API reference documentation should be generated from docstrings in the code
+- Documentation should include rich hyperlinking to other areas of the documentation, and to the API reference
+
+
+Naming Files
+------------
+
+- all lower case file names
+- if the name has multiple words, separate them with an underscore
+- all documentation file names end in '.rst'
+
+
+Heirarchy of headings
+---------------------
+
+show the heirarchy of sphinx headings we use, and the conventions (underline only, no overline)
+
+Use '=', then '-', then '~'. If your document needs more levels than that, break
+it into separate documents.
+
+You only have to worry about the heirarchy of headings within a single file. Sphinx
+handles the intra-file heirarchy magically on it's own.
+
+Use two blank lines before every heading unless it's the first heading in the file. Use one
+blank line after every heading
+
+
+Code
+----
+
+This documentation declares python as the default Sphinx domain.  Python code or interactive
+python sessions can be presented by either:
+
+- finishing the preceding paragraph with a ``::`` and indenting the code
+- use the ``.. code-block::`` directive
+
+If you want to show other code, like shell commands, then use ``.. code-block: shell``.
+
+
+Table of Contents and Captions
+------------------------------
+
+
+Hyperlinks
+----------
+
+If you want to use an external hyperlink target, define the target at the top of the page,
+not the bottom.
+
+
+We use the Sphinx `autosectionlabel <http://www.sphinx-doc.org/en/master/usage/extensions/autosectionlabel.html>`_ extension. This allows you to reference any header in any document
+by::
+
+   See :ref:`features/argument_processing:Help Messages`
+
+or ::
+
+   See :ref:`custom title<features/argument_processing:Help Messages>`
+
+Which render like
+
+See :ref:`features/argument_processing:Help Messages`
+
+and
+
+See :ref:`custom title<features/argument_processing:Help Messages>`
+
+
+
+Autolinking
+-----------
+
+
+Referencing cmd2 API documentation
+----------------------------------
+
+
+Info and Warning Callouts
+-------------------------
+
+
+Wrapping
+--------
+
+Hard wrap all text with line lengths less than 80 characters. It makes everything
+easier when editing documentation, and has no impact on reading documentation
+because we render to html.
+
+
+Referencing cmd2
+-----------------
+
+Whenever you reference ``cmd2`` in the documentation, enclose it in double backticks. This
+indicates an inline literal in restructured text, and makes it stand out when rendered as html.
+
diff --git a/docs/examples/quickstart.rst b/docs/examples/quickstart.rst
new file mode 100644
index 00000000..778cdbee
--- /dev/null
+++ b/docs/examples/quickstart.rst
@@ -0,0 +1,4 @@
+Building Your First cmd2 Application
+====================================
+
+Quickly show how to build a simple `cmd2` application.
diff --git a/docs/argument_processing.rst b/docs/features/argument_processing.rst
index a1fc107b..20ab7879 100644
--- a/docs/argument_processing.rst
+++ b/docs/features/argument_processing.rst
@@ -1,6 +1,5 @@
 .. _decorators:
 
-===================
 Argument Processing
 ===================
 
@@ -25,12 +24,16 @@ processing decorators in your ``cmd2`` applications.
 
 
 Decorators provided by cmd2 for argument processing
-===================================================
+---------------------------------------------------
+
 ``cmd2`` provides the following decorators for assisting with parsing arguments passed to commands:
 
 .. automethod:: cmd2.cmd2.with_argument_list
+   :noindex:
 .. automethod:: cmd2.cmd2.with_argparser
+   :noindex:
 .. automethod:: cmd2.cmd2.with_argparser_and_unknown_args
+   :noindex:
 
 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
@@ -38,7 +41,7 @@ command which might have its own argument parsing.
 
 
 Using the argument parser decorator
-===================================
+-----------------------------------
 
 For each command in the ``cmd2`` subclass which requires argument parsing,
 create a unique instance of ``argparse.ArgumentParser()`` which can parse the
@@ -91,7 +94,7 @@ 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``
@@ -198,7 +201,7 @@ Which yields:
 
 
 Receiving an 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
@@ -248,7 +251,8 @@ argument list instead of a string::
 
 
 Using the argument parser decorator and also receiving a list of unknown positional arguments
-===============================================================================================
+---------------------------------------------------------------------------------------------
+
 If you want all unknown arguments to be passed to your command as a list of strings, then
 decorate the command method with the ``@with_argparser_and_unknown_args`` decorator.
 
@@ -276,7 +280,8 @@ Here's what it looks like::
         ...
 
 Using custom argparse.Namespace with argument parser decorators
-===============================================================================================
+---------------------------------------------------------------
+
 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 still allowing use of the decorators, both ``@with_argparser`` and
 ``@with_argparser_and_unknown_args`` have an optional argument called ``ns_provider``.
@@ -301,7 +306,8 @@ The Namespace is passed by the decorators to the ``argparse`` parsing functions
 to the state data it needs for its parsing logic.
 
 Sub-commands
-============
+------------
+
 Sub-commands 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.
 
diff --git a/docs/features/generating_output.rst b/docs/features/generating_output.rst
new file mode 100644
index 00000000..a4a928cf
--- /dev/null
+++ b/docs/features/generating_output.rst
@@ -0,0 +1,10 @@
+Generating Output
+=================
+
+how to generate output
+
+poutput
+
+perror
+
+paging
diff --git a/docs/features/help.rst b/docs/features/help.rst
new file mode 100644
index 00000000..e5cc0451
--- /dev/null
+++ b/docs/features/help.rst
@@ -0,0 +1,8 @@
+Help
+====
+
+use the categorize() function to create help categories
+
+Use ``help_method()`` to custom roll your own help messages.
+
+See :ref:`features/argument_processing:Help Messages`
diff --git a/docs/hooks.rst b/docs/features/hooks.rst
index 5db97fe5..5db97fe5 100644
--- a/docs/hooks.rst
+++ b/docs/features/hooks.rst
diff --git a/docs/transcript.rst b/docs/features/transcript.rst
index 089ab704..089ab704 100644
--- a/docs/transcript.rst
+++ b/docs/features/transcript.rst
diff --git a/docs/freefeatures.rst b/docs/freefeatures.rst
index a06bab90..e7a4c35b 100644
--- a/docs/freefeatures.rst
+++ b/docs/freefeatures.rst
@@ -387,7 +387,7 @@ save the first 5 commands entered in this session to a text file::
     (Cmd) history :5 -o history.txt
 
 The ``history`` command can also save both the commands and their output to a
-text file. This is called a transcript. See :doc:`transcript` for more
+text file. This is called a transcript. See :doc:`features/transcript` for more
 information on how transcripts work, and what you can use them for. To create a
 transcript use the ``-t`` or ``--transcription`` option::
 
@@ -494,7 +494,7 @@ back into the app as a unit test.
 
    OK
 
-See :doc:`transcript` for more details.
+See :doc:`features/transcript` for more details.
 
 
 Tab-Completion
diff --git a/docs/index.rst b/docs/index.rst
index 5f9c4c3d..515209e8 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -1,23 +1,15 @@
-.. cmd2 documentation master file, created by
-   sphinx-quickstart on Wed Feb 10 12:05:28 2010.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-
 cmd2
 ====
 
-A python package for building powerful command-line interpreter (CLI)
-programs.  Extends the Python Standard Library's cmd_ package.
+.. default-domain:: py
 
 .. _cmd: https://docs.python.org/3/library/cmd.html
-.. _`cmd2 project page`: https://github.com/python-cmd2/cmd2
-.. _`project bug tracker`: https://github.com/python-cmd2/cmd2/issues
 
+A python package for building powerful command-line interpreter (CLI)
+programs.  Extends the Python Standard Library's cmd_ package.
 
 The basic use of ``cmd2`` is identical to that of cmd_.
 
-.. highlight:: python
-
 1. Create a subclass of ``cmd2.Cmd``.  Define attributes and
    ``do_*`` methods to control its behavior.  Throughout this documentation,
    we will assume that you are naming your subclass ``App``::
@@ -31,51 +23,108 @@ The basic use of ``cmd2`` is identical to that of cmd_.
      app = App()
      app.cmdloop()
 
-.. note::
 
-   The tab-completion feature provided by cmd_ relies on underlying capability provided by GNU readline or an
-   equivalent library.  Linux distros will almost always come with the required library installed.
-   For macOS, we recommend using the `gnureadline <https://pypi.python.org/pypi/gnureadline>`_ Python module which includes
-   a statically linked version of GNU readline.  Alternatively on macOS the ``conda`` package manager that comes
-   with the Anaconda Python distro can be used to install ``readline`` (preferably from conda-forge) or the
-   `Homebrew <https://brew.sh>`_ package manager can be used to to install the ``readline`` package.
-   For Windows, we recommend installing the `pyreadline <https://pypi.python.org/pypi/pyreadline>`_ Python module.
+Overview
+--------
 
-Resources
----------
+[create links with short descriptions to the various overview pages here]
 
-* cmd_
-* `cmd2 project page`_
-* `project bug tracker`_
-* Florida PyCon 2017: `slides <https://docs.google.com/presentation/d/1LRmpfBt3V-pYQfgQHdczf16F3hcXmhK83tl77R6IJtE>`_, `video <https://www.youtube.com/watch?v=6m0RdpITaeY>`_
+.. toctree::
+   :maxdepth: 2
+   :hidden:
+   :caption: Overview
+
+   overview/featuretour
+   overview/installation
+   overview/alternatives
+   overview/resources
+   examples/quickstart
 
-These docs will refer to ``App`` as your ``cmd2.Cmd``
-subclass, and ``app`` as an instance of ``App``.  Of
-course, in your program, you may name them whatever
-you want.
 
-Contents:
+Migrating from cmd
+------------------
+
+[create links with short descriptions to the various migrating pages here]
 
 .. toctree::
    :maxdepth: 2
+   :hidden:
+   :caption: Migrating from cmd
 
-   install
-   overview
-   freefeatures
-   settingchanges
-   unfreefeatures
-   transcript
-   argument_processing
-   integrating
-   hooks
-   alternatives
+   migrating/why
+   migrating/incompatibilities
+   migrating/minimum
+   migrating/free_features
+   migrating/nextsteps
+
+
+Features
+--------
+
+[create links with short descriptions to the various feature pages here]
+
+.. toctree::
+   :maxdepth: 2
+   :hidden:
+   :caption: Features
+
+   features/generating_output
+   features/argument_processing
+   features/help
+   features/transcript
+   features/hooks
 
-Compatibility
-=============
 
-Tested and working with Python 3.5+ on Windows, macOS, and Linux.
+Examples
+--------------------
 
-Index
-=====
+[create links with short descriptions to the various examples pages here]
+
+.. toctree::
+   :maxdepth: 2
+   :hidden:
+   :caption: Examples
 
-* :ref:`genindex`
+   examples/quickstart
+
+
+API Reference
+-------------
+
+.. toctree::
+   :maxdepth: 2
+   :hidden:
+   :caption: API Reference
+
+   api/cmd
+   api/decorators
+   api/exceptions
+   api/utility_functions
+   api/utility_classes
+
+
+Meta
+----
+
+.. toctree::
+   :maxdepth: 2
+   :hidden:
+   :caption: Meta
+
+   doc_conventions
+
+
+To Be Integrated
+----------------
+
+Files from old documentation to be integrated into new structure
+
+.. toctree::
+   :maxdepth: 2
+   :hidden:
+   :caption: To Be Integrated
+
+   freefeatures
+   integrating
+   settingchanges
+   unfreefeatures
diff --git a/docs/migrating/free_features.rst b/docs/migrating/free_features.rst
new file mode 100644
index 00000000..afb29fc3
--- /dev/null
+++ b/docs/migrating/free_features.rst
@@ -0,0 +1,5 @@
+What you get for free
+=====================
+
+A brief list (with links to details) of major features you get for free once
+you migrate.
diff --git a/docs/migrating/incompatibilities.rst b/docs/migrating/incompatibilities.rst
new file mode 100644
index 00000000..3d7ddcfb
--- /dev/null
+++ b/docs/migrating/incompatibilities.rst
@@ -0,0 +1,21 @@
+Incompatibilities
+=================
+
+.. _cmd: https://docs.python.org/3/library/cmd.html
+
+``cmd2`` strives to be drop-in compatible with cmd_, however there are a few things
+that are not.
+
+
+cmd.emptyline()
+---------------
+
+The `cmd.emptyline()
+<https://docs.python.org/3/library/cmd.html#cmd.Cmd.emptyline>`_ function is
+called when an empty line is entered in response to the prompt. By default, in
+cmd_ if this method is not overridden, it repeats and executes the last nonempty
+command entered.  However, no end user we have encountered views this as
+expected or desirable default behavior.  Thus, the default behavior in ``cmd2``
+is to simply go to the next line and issue the prompt again.  At this time, cmd2
+completely ignores empty lines and the base class cmd.emptyline() method never
+gets called and thus the emptyline() behavior cannot be overridden.
diff --git a/docs/migrating/minimum.rst b/docs/migrating/minimum.rst
new file mode 100644
index 00000000..098ba79c
--- /dev/null
+++ b/docs/migrating/minimum.rst
@@ -0,0 +1,4 @@
+Minimum required changes
+========================
+
+The minimum required changes to move to cmd2
\ No newline at end of file
diff --git a/docs/migrating/nextsteps.rst b/docs/migrating/nextsteps.rst
new file mode 100644
index 00000000..3f560501
--- /dev/null
+++ b/docs/migrating/nextsteps.rst
@@ -0,0 +1,6 @@
+Next Steps
+==========
+
+What features (with links to details) are easy to implement next
+
+:doc:`Help <../features/help>`
diff --git a/docs/migrating/why.rst b/docs/migrating/why.rst
new file mode 100644
index 00000000..d1121128
--- /dev/null
+++ b/docs/migrating/why.rst
@@ -0,0 +1,25 @@
+Why Migrate to cmd2
+===================
+
+.. _cmd: https://docs.python.org/3/library/cmd.html
+
+``cmd2`` is an extension of cmd_, the Python Standard Library's module for
+creating simple interactive command-line applications.
+
+``cmd2`` can be used as a drop-in replacement for cmd_.  Simply importing ``cmd2``
+in place of cmd_ will add many features to an application without any further
+modifications.
+
+Understanding the use of cmd_ is the first step in learning the use of ``cmd2``.
+Once you have read the cmd_ docs, return here to learn the ways that ``cmd2``
+differs from cmd_.
+
+
+Describe why you would want to migrate, and the benefits of doing so
+
+Unicode
+
+features
+
+active community
+
diff --git a/docs/overview.rst b/docs/overview.rst
deleted file mode 100644
index 75b8caa9..00000000
--- a/docs/overview.rst
+++ /dev/null
@@ -1,27 +0,0 @@
-
-========
-Overview
-========
-
-``cmd2`` is an extension of cmd_, the Python Standard Library's module for
-creating simple interactive command-line applications.
-
-``cmd2`` can be used as a drop-in replacement for cmd_.  Simply importing ``cmd2``
-in place of cmd_ will add many features to an application without any further
-modifications.
-
-Understanding the use of cmd_ is the first step in learning the use of ``cmd2``.
-Once you have read the cmd_ docs, return here to learn the ways that ``cmd2``
-differs from cmd_.
-
-.. note::
-
-   ``cmd2`` is not quite a drop-in replacement for cmd_.
-   The `cmd.emptyline() <https://docs.python.org/3/library/cmd.html#cmd.Cmd.emptyline>`_ function is called
-   when an empty line is entered in response to the prompt. By default, in cmd_ if this method is not overridden, it
-   repeats and executes the last nonempty command entered.  However, no end user we have encountered views this as
-   expected or desirable default behavior.  Thus, the default behavior in ``cmd2`` is to simply go to the next line
-   and issue the prompt again.  At this time, cmd2 completely ignores empty lines and the base class cmd.emptyline()
-   method never gets called and thus the emptyline() behavior cannot be overridden.
-
-.. _cmd: https://docs.python.org/3/library/cmd.html
diff --git a/docs/alternatives.rst b/docs/overview/alternatives.rst
index bf1545d6..bf1545d6 100644
--- a/docs/alternatives.rst
+++ b/docs/overview/alternatives.rst
diff --git a/docs/overview/featuretour.rst b/docs/overview/featuretour.rst
new file mode 100644
index 00000000..15754733
--- /dev/null
+++ b/docs/overview/featuretour.rst
@@ -0,0 +1,6 @@
+Features
+========
+
+Briefly describe the list of major features, linking to the more detailed description
+of each features elsewhere in the documentation.
+
diff --git a/docs/install.rst b/docs/overview/installation.rst
index 62765704..62765704 100644
--- a/docs/install.rst
+++ b/docs/overview/installation.rst
diff --git a/docs/overview/resources.rst b/docs/overview/resources.rst
new file mode 100644
index 00000000..487ac316
--- /dev/null
+++ b/docs/overview/resources.rst
@@ -0,0 +1,13 @@
+Resources
+=========
+
+.. _cmd: https://docs.python.org/3/library/cmd.html
+.. _`cmd2 project page`: https://github.com/python-cmd2/cmd2
+.. _`project bug tracker`: https://github.com/python-cmd2/cmd2/issues
+
+Project related links and other resources:
+
+* cmd_
+* `cmd2 project page`_
+* `project bug tracker`_
+* Florida PyCon 2017: `slides <https://docs.google.com/presentation/d/1LRmpfBt3V-pYQfgQHdczf16F3hcXmhK83tl77R6IJtE>`_, `video <https://www.youtube.com/watch?v=6m0RdpITaeY>`_