More configuration improvements and stubs.

11 files changed, 90 insertions, 78 deletions

diff --git a/docs/source/commands.rst b/docs/source/commands.rst
new file mode 100644
index 0000000..3218888
--- /dev/null
+++ b/docs/source/commands.rst
@@ -0,0 +1,13 @@
+.. _commands:
+
+Command Line Pecan
+==================
+TODO
+
+Serving Pecan App For Development
+---------------------------------
+TODO
+
+The Interactive Shell
+---------------------
+TODO
diff --git a/docs/source/configuration.rst b/docs/source/configuration.rst
index 05e6f30..9822af1 100644
--- a/docs/source/configuration.rst
+++ b/docs/source/configuration.rst
@@ -111,11 +111,11 @@ And it would be accessible in `pecan.conf` as::
     'foo_bar_user'
 
 
-Fully Valid Dictionaries
-------------------------
+Dictionary Conversion
+---------------------
 In certain situations you might want to deal with keys and values, but in strict
 dictionary form. The ``Config`` object has a helper method for this purpose
-that will return a dictionary representation of itself including nested values.
+that will return a dictionary representation of itself, including nested values.
 
 Below is a representation of how you can access the ``as_dict`` method and what
 should return as a result (shortened for brevity):
@@ -129,8 +129,8 @@ should return as a result (shortened for brevity):
     {'app': {'errors': {}, 'template_path': '', 'static_root': 'public', [...]
     
 
-Prefixing Values
-----------------
+Prefixing Dictionary Keys
+-------------------------
 ``Config.as_dict`` allows you to pass an optional argument if you need to
 prefix the keys in the returned dictionary. This is a single argument in string
 form and it works like this (shortened for brevity):
diff --git a/docs/source/deployment.rst b/docs/source/deployment.rst
index 9894467..461d004 100644
--- a/docs/source/deployment.rst
+++ b/docs/source/deployment.rst
@@ -3,8 +3,6 @@
 Deployment Recipes
 ==================
 
-Deploying Pecan projects
-========================
 Deploying a pecan project can be accomplished in several ways. You may
 already be familiar with deployment methodologies for other Python
 projects, in which case, try that! Pecan doesn't deviate from the
diff --git a/docs/source/forms.rst b/docs/source/forms.rst
new file mode 100644
index 0000000..802f55e
--- /dev/null
+++ b/docs/source/forms.rst
@@ -0,0 +1,5 @@
+.. _forms:
+
+Generating and Validating Forms
+===============================
+TODO
diff --git a/docs/source/hooks.rst b/docs/source/hooks.rst
index 99052cb..d95e21e 100644
--- a/docs/source/hooks.rst
+++ b/docs/source/hooks.rst
@@ -19,8 +19,8 @@ Hooks allow you to execute code at key points throughout the life cycle of your
 
 * ``on_error``: called when a request generates an exception
 
-Implementation
---------------
+Implementating a Pecan Hook
+---------------------------
 In the below example, we will write a simple hook that will gather
 some information about the request and print it to ``stdout``.
 
@@ -84,8 +84,8 @@ the app and browse the application from our web browser::
     response: 	 200 OK
 
 
-Included Pecan Hooks
---------------------
+Hooks That Come with Pecan
+--------------------------
 Pecan includes some hooks in its core and are very simple to start using them
 away. This section will describe their different uses, how to configure them
 and examples of common scenarios.
@@ -93,8 +93,8 @@ and examples of common scenarios.
 .. _requestviewerhook:
 
 RequestViewerHook
------------------
-This hooks is very useful for debugging purposes. It has access to every
+'''''''''''''''''
+This hook is useful for debugging purposes. It has access to every
 attribute the ``response`` object has plus a few others that are specific to
 the framework.
 
@@ -103,23 +103,25 @@ There are two main ways that this hook can provide information about a request:
 #. Terminal or logging output (via an file-like stream like `stdout`)
 #. Custom header keys in the actual response.
 
-By default, both outputs are on if they are not configured.
+By default, both outputs are enabled.
 
 For the actual object reference, please see :ref:`pecan_hooks`.
 
-Automatically Enabled
----------------------
-This hook can be automatically added to the application itself if a certain key
-exists in the configuration used for the app. This key is::
+Enabling RequestViewerHook
+..........................
+This hook can be automatically added to the application itself if a certain
+key, ``requestviewer``, exists in the configuration used for the app, e.g.::
 
-    requestviewer
+    app = {}
+    server = {}
+    requestviewer = {}
 
 It does not need to contain anything (could be an empty dictionary), and this
 is enough to force Pecan to load this hook when the WSGI application is
 created.
 
-Configuration
--------------
+Configuring RequestViewerHook
+.............................
 There are a few ways to get this hook properly configured and running. However,
 it is useful to know that no actual configuration is needed to have it up and
 running. 
@@ -137,7 +139,7 @@ No configuration will show those values in the terminal via `stdout` and it
 will also add them to the response headers (in the form of
 `X-Pecan-item_name`).
 
-This is how the terminal output look for a `/favicon.ico` request ::
+This is how the terminal output might look for a `/favicon.ico` request ::
 
     path         - /favicon.ico
     status       - 404 Not Found
@@ -146,10 +148,9 @@ This is how the terminal output look for a `/favicon.ico` request ::
     params       - []
     hooks        - ['RequestViewerHook']
 
-In the above case, the file was not found, and the information was properly
-gathered and returned via `stdout`.
-
-And this is how those same values would be seen in the response headers::
+In the above case, the file was not found, and the information was printed to
+`stdout`.  Additionally, the following headers would be present in the HTTP
+response::
 
     X-Pecan-path	/favicon.ico
     X-Pecan-status	404 Not Found
@@ -177,8 +178,8 @@ And the same configuration could be set in the config file like::
 
     requestviewer = {'items:['path']}
 
-Specifying items
-----------------
+Modifying Output Format
+.......................
 Items are the actual information objects that the hook will use to return
 information. Sometimes you will need a specific piece of information or
 a certain bunch of them according to the development need so the defaults will
@@ -248,8 +249,8 @@ And these are the specific ones from Pecan and the hook:
  * params (params is actually available from `webob` but it is parsed 
    by the hook for redability)
 
-Blacklisting
-------------
+Blacklisting Certain Paths
+..........................
 Sometimes it's annoying to get information about *every* single request. For this
 purpose, there is a matching list of url paths that you can pass into the hook
 so that paths that do not match are returned.
diff --git a/docs/source/index.rst b/docs/source/index.rst
index f005387..86bfebc 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -1,28 +1,3 @@
-Pecan Documentation
-===================
-
-A WSGI object-dispatching web framework, designed to be lean and fast,
-with few dependancies.
-
-
-Contents:
-
-.. toctree::
-   :maxdepth: 2
-   
-   installation.rst
-   quick_start.rst   
-   commands.rst
-   routing.rst
-   configuration.rst
-   templates.rst
-   rest.rst
-   secure_controller.rst
-   jsonify.rst
-   hooks.rst
-   testing.rst
-
-
 Introduction and History
 ========================
 Welcome to Pecan, a lean Python web framework inspired by CherryPy,
@@ -51,11 +26,31 @@ box, tutorials are included for integrating these yourself in just a few
 lines of code.
 
 
-Cookbook
-========
+Narrative Documentation
+=======================
+
+.. toctree::
+   :maxdepth: 2
+   
+   installation.rst
+   quick_start.rst   
+   commands.rst
+   routing.rst
+   templates.rst
+   rest.rst
+   configuration.rst
+   secure_controller.rst
+   jsonify.rst
+   hooks.rst
+   testing.rst
+
+
+Cookbook and Common Patterns
+============================
 .. toctree::
    :maxdepth: 2
 
+   forms.rst
    sessions.rst
    databases.rst
    deployment.rst
diff --git a/docs/source/quick_start.rst b/docs/source/quick_start.rst
index f2ff1f0..4a29b56 100644
--- a/docs/source/quick_start.rst
+++ b/docs/source/quick_start.rst
@@ -1,7 +1,7 @@
 .. _quick_start:
 
-Quick Start
-===========
+Creating Your First Pecan Application
+=====================================
 
 Let's create a small sample project with Pecan.
 
@@ -83,7 +83,7 @@ configuration file.
 
 .. _running_application:
 
-Running the application
+Running the Application
 -----------------------
 Before starting up your Pecan app, you'll need a configuration file.  The
 base project template should have created one for you already, ``config.py``.
@@ -148,8 +148,8 @@ For more specific documentation on configuration, see the :ref:`Configuration`
 section.
 
     
-Root Controller
----------------
+The Application Root
+--------------------
 The Root Controller is the root of your application.
 
 This is how it looks in the project template
diff --git a/docs/source/rest.rst b/docs/source/rest.rst
index 20447c3..75134d9 100644
--- a/docs/source/rest.rst
+++ b/docs/source/rest.rst
@@ -1,7 +1,7 @@
 .. _rest:
 
-REST Controller
-===============
+Writing RESTful Web Services with Pecan
+=======================================
 
 If you need to write controllers to interact with objects, using the 
 ``RestController`` may help speed things up. It follows the Representational 
@@ -63,8 +63,8 @@ The ``RestController`` still supports the ``index``, ``_default``, and
 make sure to call ``RestController._route`` at the end of your custom 
 ``_route`` method so that the REST routing described above still occurs.
 
-Nesting
--------
+Nesting ``RestController``
+---------------------------
 
 ``RestController`` instances can be nested so that child resources get the 
 parameters necessary to look up parent resources. For example::
@@ -110,8 +110,8 @@ parent controller. If the parent resource takes a variable number of arguments,
 Pecan will hand it everything up to the child resource controller name (e.g., 
 ``books`` in the above example).
 
-Custom Actions
---------------
+Defining Custom Actions
+-----------------------
 
 In addition to the default methods defined above, you can add additional 
 behaviors to a ``RestController`` by defining a special ``_custom_actions`` 
diff --git a/docs/source/routing.rst b/docs/source/routing.rst
index 498383f..e6025df 100644
--- a/docs/source/routing.rst
+++ b/docs/source/routing.rst
@@ -122,8 +122,8 @@ Please see :ref:`pecan_decorators` for more information on ``@expose``.
 
 
 
-Routing Algorithm
------------------
+Pecan's Routing Algorithm
+-------------------------
 
 Sometimes, the standard object-dispatch routing isn't adequate to properly
 route a URL to a controller. Pecan provides several ways to short-circuit 
@@ -209,8 +209,8 @@ top of Pecan, defining a base controller class that defines a ``_route`` method
 will enable you to have total control.
 
 
-Controller Arguments
---------------------
+Mapping Controller Arguments
+----------------------------
 
 In Pecan, HTTP ``GET`` and ``POST`` variables that are `not` consumed 
 during the routing process can be passed onto the controller as arguments.
diff --git a/docs/source/templates.rst b/docs/source/templates.rst
index 8f8357c..b0d9407 100644
--- a/docs/source/templates.rst
+++ b/docs/source/templates.rst
@@ -25,8 +25,8 @@ The available renderer type strings are `mako`, `genshi`, `kajiki`, `jinja`,
 and `json`.
 
 
-Using Renderers
----------------
+Using Template Renderers
+------------------------
 
 :ref:`pecan_decorators` defines a decorator called ``@expose``, which is used
 to flag a method as a controller. The ``@expose`` decorator takes a variety of
@@ -81,8 +81,8 @@ more information on using `JSON` in Pecan, please refer to :ref:`jsonify` and
 :ref:`pecan_jsonify`.
 
 
-Custom Renderers
-----------------
+Defining Custom Renderers
+-------------------------
 
 To define a custom renderer, you can create a class that follows a simple
 protocol::
diff --git a/docs/source/testing.rst b/docs/source/testing.rst
index 20a13bc..99f1fab 100644
--- a/docs/source/testing.rst
+++ b/docs/source/testing.rst
@@ -1,5 +1,5 @@
 .. _testing:
 
-Unit Testing 
-=============
+Writing Tests For Pecan Apps
+============================
 TODO