6 files changed, 298 insertions, 0 deletions
diff --git a/docs/overview/alternatives.rst b/docs/overview/alternatives.rst
new file mode 100644
index 00000000..63977334
--- /dev/null
+++ b/docs/overview/alternatives.rst
@@ -0,0 +1,54 @@
+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_.
+
+.. _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`_.
diff --git a/docs/overview/index.rst b/docs/overview/index.rst
new file mode 100644
index 00000000..231191c1
--- /dev/null
+++ b/docs/overview/index.rst
@@ -0,0 +1,15 @@
+Getting Started
+===============
+
+.. toctree::
+   :maxdepth: 1
+   :hidden:
+
+   installation
+   ../examples/first_app
+   integrating
+   alternatives
+   resources
+
+
+.. include:: summary.rst
diff --git a/docs/overview/installation.rst b/docs/overview/installation.rst
new file mode 100644
index 00000000..9f1209b6
--- /dev/null
+++ b/docs/overview/installation.rst
@@ -0,0 +1,162 @@
+
+Installation Instructions
+=========================
+
+
+.. _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``:
+
+  .. code-block:: shell
+
+    $ sudo pip install <package_name>
+
+
+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
+
+
+  On Windows:
+
+  .. code-block:: shell
+
+    > python -m pip install -U pip setuptools
+
+
+.. _`pip_install`:
+
+Install from PyPI
+-----------------
+
+pip_ is the recommended installer. Installing packages from PyPI_ with pip is
+easy:
+
+.. code-block:: shell
+
+    $ pip install cmd2
+
+This will install the required 3rd-party dependencies, if necessary.
+
+
+.. _github:
+
+Install from GitHub
+-------------------
+
+The latest version of ``cmd2`` can be installed directly from the master branch
+on GitHub using pip_:
+
+.. code-block:: shell
+
+  $ 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.
+
+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`.
+
+
+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
+
+
+macOS Considerations
+--------------------
+
+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:
+
+.. code-block:: shell
+
+  $ pip install -U gnureadline
+
+
+readline via conda
+~~~~~~~~~~~~~~~~~~
+
+Install the **readline** package using the ``conda`` package manager included
+with the Anaconda Python distribution:
+
+.. code-block:: shell
+
+  $ conda install readline
+
+
+readline via brew
+~~~~~~~~~~~~~~~~~
+
+Install the **readline** package using the Homebrew package manager (compiles
+from source):
+
+.. code-block:: shell
+
+  $ 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..e28df1a7
--- /dev/null
+++ b/docs/overview/integrating.rst
@@ -0,0 +1,32 @@
+Integrate cmd2 Into Your Project
+================================
+
+Once installed, you will want to ensure that your project's dependencies
+include ``cmd2``. Make sure your ``setup.py`` includes the following::
+
+  install_requires=[
+    'cmd2>=1,<2',
+  ]
+
+The ``cmd2`` project uses `Semantic Versioning <https://semver.org>`_, which
+means that any incompatible API changes will be release with a new major
+version number. We recommend that you follow the advice given by the Python
+Packaging User Guide related to `install_requires
+<https://packaging.python.org/discussions/install-requires-vs-requirements/>`_.
+By setting an upper bound on the allowed version, you can ensure that your
+project does not inadvertently get installed with an incompatible future
+version of ``cmd2``.
+
+
+Windows Considerations
+-------------------------------
+
+If you would like to use :ref:`features/completion:Completion`, and you want
+your application to run on Windows, you will need to ensure you install the
+``pyreadline`` package. Make sure to include the following in your
+``setup.py``::
+
+  install_requires=[
+    'cmd2>=1,<2',
+    ":sys_platform=='win32'": ['pyreadline'],
+  ]
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>`_
diff --git a/docs/overview/summary.rst b/docs/overview/summary.rst
new file mode 100644
index 00000000..9285014c
--- /dev/null
+++ b/docs/overview/summary.rst
@@ -0,0 +1,22 @@
+
+.. _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?
+
+Already built an application that uses cmd_ from the python standard library
+and want to add more functionality with very little work?
+
+``cmd2`` is a powerful python library for building command line applications.
+Start here to find out if this library is a good fit for your needs.
+
+* :ref:`overview/installation:Installation Instructions` - how to install
+  ``cmd2`` and associated optional dependencies
+* :ref:`examples/first_app:First Application` - a sample application showing 8
+  key features of ``cmd2``
+* :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