Merge "doc: Cleanup of demoapp doc"

1 files changed, 69 insertions, 95 deletions

diff --git a/doc/source/user/demoapp.rst b/doc/source/user/demoapp.rst
index 3002e78..25e376a 100644
--- a/doc/source/user/demoapp.rst
+++ b/doc/source/user/demoapp.rst
@@ -2,33 +2,27 @@
  Exploring the Demo App
 ========================
 
-The cliff source package includes a ``demoapp`` directory containing
-an example main program with several command plugins.
+The cliff source package includes a ``demoapp`` directory containing an example
+main program with several command plugins.
 
 Setup
 =====
 
-To install and experiment with the demo app you should create a
-virtual environment and activate it. This will make it easy to remove
-the app later, since it doesn't do anything useful and you aren't
-likely to want to hang onto it after you understand how it works.
-
-::
+To install and experiment with the demo app you should create a virtual
+environment and activate it. This will make it easy to remove the app later,
+since it doesn't do anything useful and you aren't likely to want to hang onto
+it after you understand how it works::
 
   $ pip install virtualenv
   $ virtualenv .venv
   $ . .venv/bin/activate
-  (.venv)$ 
-
-Next, install cliff in the same environment.
+  (.venv)$
 
-::
+Next, install cliff in the same environment::
 
   (.venv)$ python setup.py install
 
-Finally, install the demo application into the virtual environment.
-
-::
+Finally, install the demo application into the virtual environment::
 
   (.venv)$ cd demoapp
   (.venv)$ python setup.py install
@@ -36,11 +30,10 @@ Finally, install the demo application into the virtual environment.
 Usage
 =====
 
-Both cliff and the demo installed, you can now run the command
-``cliffdemo``.
+Both cliff and the demo installed, you can now run the command ``cliffdemo``.
 
-For basic command usage instructions and a list of the commands
-available from the plugins, run::
+For basic command usage instructions and a list of the commands available from
+the plugins, run::
 
   (.venv)$ cliffdemo -h
 
@@ -48,15 +41,11 @@ or::
 
   (.venv)$ cliffdemo --help
 
-Run the ``simple`` command by passing its name as argument to ``cliffdemo``.
-
-::
+Run the ``simple`` command by passing its name as argument to ``cliffdemo``::
 
   (.venv)$ cliffdemo simple
 
-The ``simple`` command prints this output to the console:
-
-::
+The ``simple`` command prints this output to the console::
 
   sending greeting
   hi!
@@ -75,8 +64,8 @@ For more information, refer to the autogenerated documentation :ref:`below
 The Source
 ==========
 
-The ``cliffdemo`` application is defined in a ``cliffdemo`` package
-containing several modules. 
+The ``cliffdemo`` application is defined in a ``cliffdemo`` package containing
+several modules.
 
 main.py
 -------
@@ -87,31 +76,28 @@ The main application is defined in ``main.py``:
    :linenos:
 
 The :class:`DemoApp` class inherits from :class:`App` and overrides
-:func:`__init__` to set the program description and version number. It
-also passes a :class:`CommandManager` instance configured to look for
-plugins in the ``cliff.demo`` namespace.
-
-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:`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``.
-
-The :func:`main` function defined in ``main.py`` is registered as a
-console script entry point so that :class:`DemoApp` can be run from
-the command line (see the discussion of ``setup.py`` below).
+:func:`__init__` to set the program description and version number. It also
+passes a :class:`CommandManager` instance configured to look for plugins in the
+``cliff.demo`` namespace.
+
+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:`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``.
+
+The :func:`main` function defined in ``main.py`` is registered as a console
+script entry point so that :class:`DemoApp` can be run from the command line
+(see the discussion of ``setup.py`` below).
 
 simple.py
 ---------
@@ -121,11 +107,9 @@ Two commands are defined in ``simple.py``:
 .. literalinclude:: ../../../demoapp/cliffdemo/simple.py
    :linenos:
 
-:class:`Simple` demonstrates using logging to emit messages on the
-console at different verbose levels.
+:class:`Simple` demonstrates using logging to emit messages on the console at
+different verbose levels::
 
-::
-    
     (.venv)$ cliffdemo simple
     sending greeting
     hi!
@@ -140,23 +124,21 @@ console at different verbose levels.
     (.venv)$ cliffdemo -q simple
     hi!
 
-:class:`Error` always raises a :class:`RuntimeError` exception when it
-is invoked, and can be used to experiment with the error handling
-features of cliff.
+:class:`Error` always raises a :class:`RuntimeError` exception when it is
+invoked, and can be used to experiment with the error handling features of
+cliff::
 
-::
-    
     (.venv)$ cliffdemo error
     causing error
     ERROR: this is the expected exception
-    
+
     (.venv)$ cliffdemo -v error
     prepare_to_run_command Error
     causing error
     ERROR: this is the expected exception
     clean_up Error
     got an error: this is the expected exception
-    
+
     (.venv)$ cliffdemo --debug error
     causing error
     this is the expected exception
@@ -188,18 +170,15 @@ features of cliff.
 list.py
 -------
 
-``list.py`` includes a single command derived from
-:class:`cliff.lister.Lister` which prints a list of the files in the
-current directory.
+``list.py`` includes a single command derived from :class:`cliff.lister.Lister`
+which prints a list of the files in the current directory.
 
 .. literalinclude:: ../../../demoapp/cliffdemo/list.py
    :linenos:
 
-:class:`Files` prepares the data, and :class:`Lister` manages the
-output formatter and printing the data to the console.
+:class:`Files` prepares the data, and :class:`Lister` manages the output
+formatter and printing the data to the console::
 
-::
-    
     (.venv)$ cliffdemo files
     +---------------+------+
     |      Name     | Size |
@@ -209,7 +188,7 @@ output formatter and printing the data to the console.
     | Makefile      | 5569 |
     | source        |  408 |
     +---------------+------+
-    
+
     (.venv)$ cliffdemo files -f csv
     "Name","Size"
     "build",136
@@ -222,17 +201,14 @@ output formatter and printing the data to the console.
 show.py
 -------
 
-``show.py`` includes a single command derived from
-:class:`cliff.show.ShowOne` which prints the properties of the named
-file.
+``show.py`` includes a single command derived from :class:`cliff.show.ShowOne`
+which prints the properties of the named file.
 
 .. literalinclude:: ../../../demoapp/cliffdemo/show.py
    :linenos:
 
-:class:`File` prepares the data, and :class:`ShowOne` manages the
-output formatter and printing the data to the console.
-
-::
+:class:`File` prepares the data, and :class:`ShowOne` manages the output
+formatter and printing the data to the console::
 
     (.venv)$ cliffdemo file setup.py
     +---------------+--------------+
@@ -253,32 +229,30 @@ The demo application is packaged using setuptools.
 .. literalinclude:: ../../../demoapp/setup.py
    :linenos:
 
-The important parts of the packaging instructions are the
-``entry_points`` settings. All of the commands are registered in the
-``cliff.demo`` namespace. Each main program should define its own
-command namespace so that it only loads the command plugins that it
-should be managing.
+The important parts of the packaging instructions are the ``entry_points``
+settings. All of the commands are registered in the ``cliff.demo`` namespace.
+Each main program should define its own command namespace so that it only loads
+the command plugins that it should be managing.
 
 Command Extension Hooks
 =======================
 
-Individual subcommands of an application can be extended via hooks
-registered as separate plugins. In the demo application, the
-``hooked`` command has a single extension registered.
+Individual subcommands of an application can be extended via hooks registered
+as separate plugins. In the demo application, the ``hooked`` command has a
+single extension registered.
 
-The namespace for hooks is a combination of the application namespace
-and the command name. In this case, the application namespace is
-``cliff.demo`` and the command is ``hooked``, so the extension
-namespace is ``cliff.demo.hooked``. If the subcommand name includes
-spaces, they are replaced with underscores ("``_``") to build the
-namespace.
+The namespace for hooks is a combination of the application namespace and the
+command name. In this case, the application namespace is ``cliff.demo`` and the
+command is ``hooked``, so the extension namespace is ``cliff.demo.hooked``. If
+the subcommand name includes spaces, they are replaced with underscores
+("``_``") to build the namespace.
 
 .. literalinclude:: ../../../demoapp/cliffdemo/hook.py
    :linenos:
 
-Although the ``hooked`` command does not add any arguments to the
-parser it creates, the help output shows that the extension adds a
-single ``--added-by-hook`` option.
+Although the ``hooked`` command does not add any arguments to the parser it
+creates, the help output shows that the extension adds a single
+``--added-by-hook`` option.
 
 ::