Revise menu structure

- collapse menu structure in sidebar so not everything is always shown
- updates to Getting Started section

11 files changed, 248 insertions, 165 deletions

diff --git a/docs/api/index.rst b/docs/api/index.rst
new file mode 100644
index 00000000..fd8cec36
--- /dev/null
+++ b/docs/api/index.rst
@@ -0,0 +1,11 @@
+API
+===
+
+.. toctree::
+   :maxdepth: 1
+
+   cmd
+   decorators
+   exceptions
+   utility_functions
+   utility_classes
diff --git a/docs/examples/index.rst b/docs/examples/index.rst
new file mode 100644
index 00000000..f068f6ca
--- /dev/null
+++ b/docs/examples/index.rst
@@ -0,0 +1,7 @@
+Examples
+========
+
+.. toctree::
+   :maxdepth: 1
+
+   quickstart
diff --git a/docs/features/index.rst b/docs/features/index.rst
new file mode 100644
index 00000000..ae2933e2
--- /dev/null
+++ b/docs/features/index.rst
@@ -0,0 +1,24 @@
+Features
+========
+
+.. toctree::
+   :maxdepth: 1
+
+   generating_output
+   argument_processing
+   prompt
+   help
+   history
+   startup_commands
+   shortcuts_aliases_macros
+   settings
+   completion
+   os
+   multiline
+   disable_commands
+   clipboard
+   transcript
+   hooks
+   plugins
+   scripting
+   embedded_python_shells
diff --git a/docs/index.rst b/docs/index.rst
index df9a1513..68106d9f 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -24,21 +24,16 @@ The basic use of ``cmd2`` is identical to that of cmd_.
      app.cmdloop()
 
 
-Overview
---------
+Getting Started
+---------------
 
-[create links with short descriptions to the various overview pages here]
+.. include:: overview/summary.rst
 
 .. toctree::
    :maxdepth: 2
    :hidden:
-   :caption: Overview
 
-   overview/featuretour
-   overview/installation
-   overview/alternatives
-   overview/resources
-   examples/quickstart
+   overview/index
 
 
 Migrating from cmd
@@ -48,14 +43,8 @@ Migrating from cmd
 
 .. toctree::
    :maxdepth: 2
-   :hidden:
-   :caption: Migrating from cmd
 
-   migrating/why
-   migrating/incompatibilities
-   migrating/minimum
-   migrating/free_features
-   migrating/nextsteps
+   migrating/index
 
 
 Features
@@ -65,55 +54,28 @@ Features
 
 .. toctree::
    :maxdepth: 2
-   :hidden:
-   :caption: Features
-
-   features/generating_output
-   features/argument_processing
-   features/prompt
-   features/help
-   features/history
-   features/startup_commands
-   features/shortcuts_aliases_macros
-   features/settings
-   features/completion
-   features/os
-   features/multiline
-   features/disable_commands
-   features/clipboard
-   features/transcript
-   features/hooks
-   features/plugins
-   features/scripting
-   features/embedded_python_shells
 
+   features/index
 
-Examples
---------------------
 
-[create links with short descriptions to the various examples pages here]
+API Reference
+-------------
 
 .. toctree::
    :maxdepth: 2
-   :hidden:
-   :caption: Examples
 
-   examples/quickstart
+   api/index
 
 
-API Reference
--------------
+Examples
+--------------------
+
+[create links with short descriptions to the various examples pages here]
 
 .. toctree::
    :maxdepth: 2
-   :hidden:
-   :caption: API Reference
 
-   api/cmd
-   api/decorators
-   api/exceptions
-   api/utility_functions
-   api/utility_classes
+   examples/index
 
 
 Meta
diff --git a/docs/migrating/index.rst b/docs/migrating/index.rst
new file mode 100644
index 00000000..9c01b1bd
--- /dev/null
+++ b/docs/migrating/index.rst
@@ -0,0 +1,11 @@
+Migrating from cmd
+==================
+
+.. toctree::
+   :maxdepth: 1
+
+   why
+   incompatibilities
+   minimum
+   free_features
+   nextsteps
diff --git a/docs/overview/alternatives.rst b/docs/overview/alternatives.rst
index bf1545d6..e8e8e3b3 100644
--- a/docs/overview/alternatives.rst
+++ b/docs/overview/alternatives.rst
@@ -1,13 +1,11 @@
-============================
-Alternatives to cmd and cmd2
-============================
+Alternatives
+============
 
-For programs that do not interact with the user in a continuous loop -
-programs that simply accept a set of arguments from the command line, return
-results, and do not keep the user within the program's environment - all
-you need are sys_\ .argv (the command-line arguments) and argparse_
-(for parsing UNIX-style options and flags).  Though some people may prefer docopt_
-or click_ to argparse_.
+For programs that do not interact with the user in a continuous loop - programs
+that simply accept a set of arguments from the command line, return results, and
+do not keep the user within the program's environment - all you need are sys_\
+.argv (the command-line arguments) and argparse_ (for parsing UNIX-style options
+and flags).  Though some people may prefer docopt_ or click_ to argparse_.
 
 .. _sys: https://docs.python.org/3/library/sys.html
 .. _argparse: https://docs.python.org/3/library/argparse.html
@@ -15,39 +13,43 @@ or click_ to argparse_.
 .. _click: http://click.pocoo.org
 
 
-The curses_ module produces applications that interact via a plaintext
-terminal window, but are not limited to simple text input and output;
-they can paint the screen with options that are selected from using the
-cursor keys.  However, programming a curses_-based application is not as
-straightforward as using cmd_.
+The curses_ module produces applications that interact via a plaintext terminal
+window, but are not limited to simple text input and output; they can paint the
+screen with options that are selected from using the cursor keys.  However,
+programming a curses_-based application is not as straightforward as using cmd_.
 
 .. _curses: https://docs.python.org/3/library/curses.html
 .. _cmd: https://docs.python.org/3/library/cmd.html
 
 Several Python packages exist for building interactive command-line applications
-approximately similar in concept to cmd_ applications.  None of them
-share ``cmd2``'s close ties to cmd_, but they may be worth investigating
-nonetheless.  Two of the most mature and full featured are:
+approximately similar in concept to cmd_ applications.  None of them share
+``cmd2``'s close ties to cmd_, but they may be worth investigating nonetheless.
+Two of the most mature and full featured are:
 
   * `Python Prompt Toolkit`_
   * Click_
 
 .. _`Python Prompt Toolkit`: https://github.com/jonathanslenders/python-prompt-toolkit
 
-`Python Prompt Toolkit`_ is a library for building powerful interactive command lines and terminal applications in
-Python.  It provides a lot of advanced visual features like syntax highlighting, bottom bars, and the ability to
-create fullscreen apps.
+`Python Prompt Toolkit`_ is a library for building powerful interactive command
+lines and terminal applications in Python.  It provides a lot of advanced visual
+features like syntax highlighting, bottom bars, and the ability to create
+fullscreen apps.
 
-Click_ is a Python package for creating beautiful command line interfaces in a composable way with as little code as
-necessary.  It is more geared towards command line utilities instead of command line interpreters, but it can be used
+Click_ is a Python package for creating beautiful command line interfaces in a
+composable way with as little code as necessary.  It is more geared towards
+command line utilities instead of command line interpreters, but it can be used
 for either.
 
-Getting a working command-interpreter application based on either `Python Prompt Toolkit`_ or Click_ requires a good
-deal more effort and boilerplate code than ``cmd2``.  ``cmd2`` focuses on providing an excellent out-of-the-box experience
-with as many useful features as possible built in for free with as little work required on the developer's part as
-possible.  We believe that ``cmd2`` provides developers the easiest way to write a command-line interpreter, while
-allowing a good experience for end users.  If you are seeking a visually richer end-user experience and don't
-mind investing more development time, we would recommend checking out `Python Prompt Toolkit`_.
-
-In the future, we may investigate options for incorporating the usage of `Python Prompt Toolkit`_ and/or Click_ into
-``cmd2`` applications.
+Getting a working command-interpreter application based on either `Python Prompt
+Toolkit`_ or Click_ requires a good deal more effort and boilerplate code than
+``cmd2``.  ``cmd2`` focuses on providing an excellent out-of-the-box experience
+with as many useful features as possible built in for free with as little work
+required on the developer's part as possible.  We believe that ``cmd2`` provides
+developers the easiest way to write a command-line interpreter, while allowing a
+good experience for end users.  If you are seeking a visually richer end-user
+experience and don't mind investing more development time, we would recommend
+checking out `Python Prompt Toolkit`_.
+
+In the future, we may investigate options for incorporating the usage of `Python
+Prompt Toolkit`_ and/or Click_ into ``cmd2`` applications.
diff --git a/docs/overview/featuretour.rst b/docs/overview/featuretour.rst
index 15754733..a0d33da4 100644
--- a/docs/overview/featuretour.rst
+++ b/docs/overview/featuretour.rst
@@ -1,6 +1,5 @@
-Features
-========
-
-Briefly describe the list of major features, linking to the more detailed description
-of each features elsewhere in the documentation.
+Feature Highlights
+==================
 
+[Briefly describe the list of major features, linking to the more detailed description
+of each features elsewhere in the documentation.]
diff --git a/docs/overview/index.rst b/docs/overview/index.rst
new file mode 100644
index 00000000..54415a33
--- /dev/null
+++ b/docs/overview/index.rst
@@ -0,0 +1,15 @@
+Getting Started
+===============
+
+.. toctree::
+   :maxdepth: 1
+   :hidden:
+
+   featuretour
+   installation
+   integrating
+   alternatives
+   resources
+   ../examples/quickstart
+
+.. include:: summary.rst
diff --git a/docs/overview/installation.rst b/docs/overview/installation.rst
index 62765704..fc44e740 100644
--- a/docs/overview/installation.rst
+++ b/docs/overview/installation.rst
@@ -2,110 +2,99 @@
 Installation Instructions
 =========================
 
-This section covers the basics of how to install, upgrade, and uninstall ``cmd2``.
-
-Installing
-----------
-First you need to make sure you have Python 3.5+, pip_, and setuptools_.  Then you can just use pip to
-install from PyPI_.
 
 .. _pip: https://pypi.python.org/pypi/pip
 .. _setuptools: https://pypi.python.org/pypi/setuptools
 .. _PyPI: https://pypi.python.org/pypi
 
+``cmd2`` works on Linux, macOS, and Windows. It requires Python 3.5 or
+higher, pip_, and setuptools_. If you've got all that, then you can just:
+
+.. code-block:: shell
+
+   $ pip install cmd2
+
 .. note::
 
-  Depending on how and where you have installed Python on your system and on what OS you are using, you may need to
-  have administrator or root privileges to install Python packages.  If this is the case, take the necessary steps
-  required to run the commands in this section as root/admin, e.g.: on most Linux or Mac systems, you can precede them
-  with ``sudo``::
+  Depending on how and where you have installed Python on your system and on
+  what OS you are using, you may need to have administrator or root privileges
+  to install Python packages.  If this is the case, take the necessary steps
+  required to run the commands in this section as root/admin, e.g.: on most
+  Linux or Mac systems, you can precede them with ``sudo``:
 
-    sudo pip install <package_name>
+  .. code-block:: shell
 
+    $ sudo pip install <package_name>
 
-Requirements for Installing
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-* If you have Python 3 >=3.5 installed from `python.org
-  <https://www.python.org>`_, you will already have pip_ and
-  setuptools_, but may need to upgrade to the latest versions:
+
+Prerequisites
+-------------
+
+If you have Python 3 >=3.5 installed from `python.org
+<https://www.python.org>`_, you will already have pip_ and setuptools_, but may
+need to upgrade to the latest versions:
 
   On Linux or OS X:
 
-  ::
+  .. code-block:: shell
 
-    pip install -U pip setuptools
+    $ pip install -U pip setuptools
 
 
   On Windows:
 
-  ::
+  .. code-block:: shell
 
-    python -m pip install -U pip setuptools
+    > python -m pip install -U pip setuptools
 
 
 .. _`pip_install`:
 
-Use pip for Installing
-~~~~~~~~~~~~~~~~~~~~~~
+Install from PyPI
+-----------------
+
+pip_ is the recommended installer. Installing packages from PyPI_ with pip is
+easy:
 
-pip_ is the recommended installer. Installing packages from PyPI_ with pip is easy::
+.. code-block:: shell
 
-    pip install cmd2
+    $ pip install cmd2
 
-This should also install the required 3rd-party dependencies, if necessary.
+This will install the required 3rd-party dependencies, if necessary.
 
 
 .. _github:
 
-Install from GitHub using pip
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Install from GitHub
+-------------------
 
-The latest version of ``cmd2`` can be installed directly from the master branch on GitHub using pip_::
+The latest version of ``cmd2`` can be installed directly from the master branch
+on GitHub using pip_:
 
-  pip install -U git+git://github.com/python-cmd2/cmd2.git
+.. code-block:: shell
 
-This should also install the required 3rd-party dependencies, if necessary.
+  $ pip install -U git+git://github.com/python-cmd2/cmd2.git
 
 
 Install from Debian or Ubuntu repos
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-We recommend installing from pip_, but if you wish to install from Debian or Ubuntu repos this can be done with
-apt-get.
+-----------------------------------
+
+We recommend installing from pip_, but if you wish to install from Debian or
+Ubuntu repos this can be done with apt-get.
 
 For Python 3::
 
-    sudo apt-get install python3-cmd2
+    $ sudo apt-get install python3-cmd2
 
 This will also install the required 3rd-party dependencies.
 
 .. warning::
 
-  Versions of ``cmd2`` before 0.7.0 should be considered to be of unstable "beta" quality and should not be relied upon
-  for production use.  If you cannot get a version >= 0.7 from your OS repository, then we recommend
-  installing from either pip or GitHub - see :ref:`pip_install` or :ref:`github`.
-
-
-Deploy cmd2.py with your project
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-``cmd2`` is contained in a small number of Python files, which can be easily copied into your project.  *The
-copyright and license notice must be retained*.
-
-This is an option suitable for advanced Python users.  You can simply include the files within your project's hierarchy.
-If you want to modify ``cmd2``, this may be a reasonable option.  Though, we encourage you to use stock ``cmd2`` and
-either composition or inheritance to achieve the same goal.
-
-This approach will obviously NOT automatically install the required 3rd-party dependencies, so you need to make sure
-the following Python packages are installed:
-
-  * attrs
-  * colorama
-  * pyperclip
-  * wcwidth
-
-On Windows, there is an additional dependency:
-
-  * pyreadline
+  Versions of ``cmd2`` before 0.7.0 should be considered to be of unstable
+  "beta" quality and should not be relied upon for production use.  If you
+  cannot get a version >= 0.7 from your OS repository, then we recommend
+  installing from either pip or GitHub - see :ref:`pip_install` or
+  :ref:`github`.
 
 
 Upgrading cmd2
@@ -122,34 +111,51 @@ Uninstalling cmd2
 -----------------
 If you wish to permanently uninstall ``cmd2``, this can also easily be done with pip_::
 
-    pip uninstall cmd2
+    $ pip uninstall cmd2
+
 
+macOS Considerations
+--------------------
 
-Extra requirement for macOS
-===========================
-macOS comes with the `libedit <http://thrysoee.dk/editline/>`_ library which is similar, but not identical, to GNU Readline.
-Tab-completion for ``cmd2`` applications is only tested against GNU Readline.
+macOS comes with the `libedit <http://thrysoee.dk/editline/>`_ library which is
+similar, but not identical, to GNU Readline. Tab-completion for ``cmd2``
+applications is only tested against GNU Readline.
+
+There are several ways GNU Readline can be installed within a Python environment
+on a Mac, detailed in the following subsections.
 
-There are several ways GNU Readline can be installed within a Python environment on a Mac, detailed in the following subsections.
 
 gnureadline Python module
--------------------------
-Install the `gnureadline <https://pypi.python.org/pypi/gnureadline>`_ Python module which is statically linked against a specific compatible version of GNU Readline::
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Install the `gnureadline <https://pypi.python.org/pypi/gnureadline>`_ Python module which is statically linked against a specific compatible version of GNU Readline:
+
+.. code-block:: shell
+
+  $ pip install -U gnureadline
 
-  pip install -U gnureadline
 
 readline via conda
-------------------
-Install the **readline** package using the ``conda`` package manager included with the Anaconda Python distribution::
+~~~~~~~~~~~~~~~~~~
+
+Install the **readline** package using the ``conda`` package manager included
+with the Anaconda Python distribution:
+
+.. code-block:: shell
+
+  $ conda install readline
 
-  conda install readline
 
 readline via brew
------------------
-Install the **readline** package using the Homebrew package manager (compiles from source)::
+~~~~~~~~~~~~~~~~~
+
+Install the **readline** package using the Homebrew package manager (compiles
+from source):
+
+.. code-block:: shell
 
-  brew install openssl
-  brew install pyenv
-  brew install readline
+  $ brew install openssl
+  $ brew install pyenv
+  $ brew install readline
 
 Then use pyenv to compile Python and link against the installed readline
diff --git a/docs/overview/integrating.rst b/docs/overview/integrating.rst
new file mode 100644
index 00000000..b3770559
--- /dev/null
+++ b/docs/overview/integrating.rst
@@ -0,0 +1,27 @@
+Integrate cmd2 into your project
+--------------------------------
+
+[TODO - show how to use semantic versions to add the correct version string to setup.py ]
+
+[TODO - this is probably outdated advice]
+
+``cmd2`` is contained in a small number of Python files, which can be easily
+copied into your project.  *The copyright and license notice must be retained*.
+
+This is an option suitable for advanced Python users.  You can simply include
+the files within your project's hierarchy. If you want to modify ``cmd2``, this
+may be a reasonable option.  Though, we encourage you to use stock ``cmd2`` and
+either composition or inheritance to achieve the same goal.
+
+This approach will obviously NOT automatically install the required 3rd-party
+dependencies, so you need to make sure the following Python packages are
+installed:
+
+  * attrs
+  * colorama
+  * pyperclip
+  * wcwidth
+
+On Windows, there is an additional dependency:
+
+  * pyreadline
\ No newline at end of file
diff --git a/docs/overview/summary.rst b/docs/overview/summary.rst
new file mode 100644
index 00000000..4145d124
--- /dev/null
+++ b/docs/overview/summary.rst
@@ -0,0 +1,19 @@
+
+.. _cmd: https://docs.python.org/3/library/cmd.html
+
+Building a new `REPL <https://en.wikipedia.org/wiki/Read–eval–print_loop>`_ or
+`Command Line Interface <https://en.wikipedia.org/wiki/Command-line_interface>`_
+application? ``cmd2`` is a powerful python library to help you get the job done.
+Already built an application that uses cmd_ from the python standard library and
+want to add more functionality with very little work? Begin here to find out if
+``cmd2`` is a good fit for your needs.
+
+* :ref:`overview/featuretour:Feature Highlights` - a quick tour of a few of the
+  features in ``cmd2``, for both developers and users
+* :ref:`overview/installation:Installation Instructions` - how to install
+  ``cmd2`` and associated optional dependencies
+* :ref:`overview/integrating:Integrate cmd2 Into Your Project` - adding ``cmd2``
+  to your project
+* :ref:`overview/alternatives:Alternatives` - other python packages that might
+  meet your needs
+* :ref:`overview/resources:Resources` - related links and other materials