documentation improvements

6 files changed, 126 insertions, 6 deletions

diff --git a/docs/source/classes.rst b/docs/source/classes.rst
index a1cadbb..65abd4e 100644
--- a/docs/source/classes.rst
+++ b/docs/source/classes.rst
@@ -8,6 +8,12 @@ App
 .. autoclass:: cliff.app.App
    :members:
 
+InteractiveApp
+==============
+
+.. autoclass:: cliff.interactive.InteractiveApp
+   :members:
+
 CommandManager
 ==============
 
diff --git a/docs/source/demoapp.rst b/docs/source/demoapp.rst
index 1832077..84ca5d3 100644
--- a/docs/source/demoapp.rst
+++ b/docs/source/demoapp.rst
@@ -85,14 +85,20 @@ The :class:`DemoApp` class inherits from :class:`App` and overrides
 also passes a :class:`CommandManager` instance configured to look for
 plugins in the ``cliff.demo`` namespace.
 
-The :func:`prepare_to_run_command` method of :class:`DemoApp` will be
-invoked after the main program arguments are parsed and the command is
-identified, but before the command is given its arguments and
-run. This hook is intended for opening connections to remote web
+The :func:`initialize_app` method of :class:`DemoApp` will be invoked
+after the main program arguments are parsed, but before any command
+processing is performed and before the application enters interactive
+mode. This hook is intended for opening connections to remote web
 services, databases, etc. using arguments passed to the main
 application.
 
-The :func:`clean_up` method of :class:`DemoApp` is invoked after the
+The :func:`prepare_to_run_command` method of :class:`DemoApp` will be
+invoked after a command is identified, but before the command is given
+its arguments and run. This hook is intended for pre-command
+validation or setup that must be repeated and cannot be handled by
+:func:`initialize_app`.
+
+The :func:`clean_up` method of :class:`DemoApp` is invoked after a
 command runs. If the command raised an exception, the exception object
 is passed to :func:`clean_up`. Otherwise the ``err`` argument is
 ``None``.
diff --git a/docs/source/history.rst b/docs/source/history.rst
index 303b9cd..58b5fb3 100644
--- a/docs/source/history.rst
+++ b/docs/source/history.rst
@@ -5,6 +5,8 @@
 dev
 
   - Add shell formatter for single objects.
+  - Add interactive mode.
+  - Expand documentation.
 
 0.3
 
diff --git a/docs/source/index.rst b/docs/source/index.rst
index 8994669..0a13664 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -15,6 +15,7 @@ Contents:
    demoapp
    list_commands
    show_commands
+   interactive_mode
    classes
    install
    developers
@@ -27,3 +28,5 @@ Indices and tables
 * :ref:`genindex`
 * :ref:`modindex`
 * :ref:`search`
+
+.. todolist::
diff --git a/docs/source/interactive_mode.rst b/docs/source/interactive_mode.rst
new file mode 100644
index 0000000..519e89a
--- /dev/null
+++ b/docs/source/interactive_mode.rst
@@ -0,0 +1,94 @@
+==================
+ Interactive Mode
+==================
+
+In addition to running single commands from the command line, cliff
+supports an interactive mode in which the user is presented with a
+separate command shell. All of the command plugins available from the
+command line are automatically configured as commands within the
+shell.
+
+Refer to the cmd2_ documentation for more details about features of
+the shell.
+
+.. _cmd2: http://packages.python.org/cmd2/index.html
+
+.. todo:: Add details about configuring and interacting with the shell (copy from cmd2 docs)
+
+Example
+=======
+
+The ``cliffdemo`` application enters interactive mode if no command is
+specified on the command line.
+
+::
+
+    (.venv)$ cliffdemo
+    (cliffdemo) help
+    
+    Shell commands (type help <topic>):
+    ===================================
+    cmdenvironment  edit  hi       l   list  pause  r    save  shell      show
+    ed              help  history  li  load  py     run  set   shortcuts
+    
+    Undocumented commands:
+    ======================
+    EOF  eof  exit  q  quit
+    
+    Application commands (type help <topic>):
+    =========================================
+    files  help  simple  file  error  two part
+
+To obtain instructions for a built-in or application command, use the
+``help`` command:
+
+::
+    
+    (cliffdemo) help simple
+    usage: simple [-h]
+    
+    A simple command that prints a message.
+    
+    optional arguments:
+      -h, --help  show this help message and exit
+
+The commands can be run, including options and arguments, as on the
+regular command line:
+
+::
+    
+    (cliffdemo) simple
+    sending greeting
+    hi!
+    (cliffdemo) files
+    +----------------------+-------+
+    |         Name         |  Size |
+    +----------------------+-------+
+    | .git                 |   578 |
+    | .gitignore           |   268 |
+    | .tox                 |   238 |
+    | .venv                |   204 |
+    | announce.rst         |  1015 |
+    | announce.rst~        |   708 |
+    | cliff                |   884 |
+    | cliff.egg-info       |   340 |
+    | cliffdemo.log        |  2193 |
+    | cliffdemo.log.1      | 10225 |
+    | demoapp              |   408 |
+    | dist                 |   136 |
+    | distribute_setup.py  | 15285 |
+    | distribute_setup.pyc | 15196 |
+    | docs                 |   238 |
+    | LICENSE              | 11358 |
+    | Makefile             |   376 |
+    | Makefile~            |    94 |
+    | MANIFEST.in          |   186 |
+    | MANIFEST.in~         |   344 |
+    | README.rst           |  1063 |
+    | setup.py             |  5855 |
+    | setup.py~            |  8128 |
+    | tests                |   204 |
+    | tox.ini              |    76 |
+    | tox.ini~             |   421 |
+    +----------------------+-------+
+    (cliffdemo) 
diff --git a/docs/source/introduction.rst b/docs/source/introduction.rst
index afef2bf..0951f19 100644
--- a/docs/source/introduction.rst
+++ b/docs/source/introduction.rst
@@ -19,7 +19,7 @@ fit.
 Cliff Objects
 =============
 
-Cliff is organized around three objects that are combined to create a
+Cliff is organized around four objects that are combined to create a
 useful command line program.
 
 The Application
@@ -50,6 +50,15 @@ responsible for taking action based on instructions from the user. It
 defines its own local argument parser (usually using argparse_) and a
 :func:`run` method that does the appropriate work.
 
+The Interactive Application
+---------------------------
+
+The main program uses an :class:`cliff.interactive.InteractiveApp`
+instance to provide a command-shell mode in which the user can type
+multiple commands before the program exits. Many cliff-based
+applications will be able to use the default implementation of
+:class:`InteractiveApp` without subclassing it.
+
 .. _setuptools entry points: http://packages.python.org/distribute/setuptools.html
 
 .. _argparse: http://docs.python.org/library/argparse.html