Major overhaul of documentation structure for #709

4 files changed, 227 insertions, 0 deletions

diff --git a/docs/overview/alternatives.rst b/docs/overview/alternatives.rst
new file mode 100644
index 00000000..bf1545d6
--- /dev/null
+++ b/docs/overview/alternatives.rst
@@ -0,0 +1,53 @@
+============================
+Alternatives to cmd and cmd2
+============================
+
+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
+.. _docopt: https://pypi.python.org/pypi/docopt
+.. _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_.
+
+.. _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:
+
+  * `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.
+
+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.
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/overview/installation.rst b/docs/overview/installation.rst
new file mode 100644
index 00000000..62765704
--- /dev/null
+++ b/docs/overview/installation.rst
@@ -0,0 +1,155 @@
+
+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
+
+.. 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``::
+
+    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:
+
+  On Linux or OS X:
+
+  ::
+
+    pip install -U pip setuptools
+
+
+  On Windows:
+
+  ::
+
+    python -m pip install -U pip setuptools
+
+
+.. _`pip_install`:
+
+Use pip for Installing
+~~~~~~~~~~~~~~~~~~~~~~
+
+pip_ is the recommended installer. Installing packages from PyPI_ with pip is easy::
+
+    pip install cmd2
+
+This should also install the required 3rd-party dependencies, if necessary.
+
+
+.. _github:
+
+Install from 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
+
+This should also install the required 3rd-party dependencies, if necessary.
+
+
+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.
+
+For Python 3::
+
+    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
+
+
+Upgrading cmd2
+--------------
+
+Upgrade an already installed ``cmd2`` to the latest version from PyPI_::
+
+    pip install -U cmd2
+
+This will upgrade to the newest stable version of ``cmd2`` and will also upgrade any dependencies if necessary.
+
+
+Uninstalling cmd2
+-----------------
+If you wish to permanently uninstall ``cmd2``, this can also easily be done with pip_::
+
+    pip uninstall cmd2
+
+
+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.
+
+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::
+
+  pip install -U gnureadline
+
+readline via conda
+------------------
+Install the **readline** package using the ``conda`` package manager included with the Anaconda Python distribution::
+
+  conda install readline
+
+readline via brew
+-----------------
+Install the **readline** package using the Homebrew package manager (compiles from source)::
+
+  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/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>`_