added API information about hooks

docs/0.0.1/source/hooks.rst

@@ -0,0 +1,72 @@
+.. _hooks:
+
+Hooks
+=====
+Pecan Hooks are a nice way to interact with the framework itself rather than
+writing middleware.
+
+There is nothing wrong with WSGI Middleware, and actually, it is really easy to
+use middleware with Pecan, but it is rather hard (sometimes impossible) to have
+access to Pecan's internals.
+
+Hooks offer three ways of dealing with a request: *before*, *after* and
+*on_error* . Obviously,
+an *after* hook will be triggered once the request has been processed, a *before* hook will
+be dealt before anything and a *on_error* will be called when the request
+generated an error.
+
+
+Implementation
+--------------
+They are very easy to plug into Pecan. In the below example we will go through
+a simple hooks that will gather some information about the request and then it
+will print it out to ``stdout``.
+
+Your hook needs to import ``PecanHook`` which will be used to inherit from.
+
+This is how your hook file should look like::
+
+    from pecan.hooks import PecanHook
+
+    class SimpleHook(PecanHook):
+
+        def after(self, state):
+            print "\nmethod: \t %s" % state.request.method
+            print "response: \t %s" % state.response.status
+
+The ``after`` method will be called after the request has been dealt with.
+
+If you save your file as ``my_hook.py`` you should be able to add it to your 
+application like this::
+
+    from application.root import RootController
+    from my_hook import SimpleHook
+
+    app = make_app(
+        RootController(),
+        hooks           = [SimpleHook()]
+        )
+
+We are passing the ``RootController`` of our application (make sure to replace
+the bogus values with your own) and our ``SimpleHook`` goes into a list for the
+``hooks`` parameter.
+
+We are not displaying how the entire file should look like but showing what is
+of interest to get a hook into Pecan.
+
+Running it
+----------
+Now that our ``SimpleHook`` is passed on, let's see what happens when we run
+the app and browse the application::
+
+    python start.py config
+    Serving on http://0.0.0.0:8080
+    serving on 0.0.0.0:8080 view at http://127.0.0.1:8080
+
+    method: 	 GET
+    response: 	 200 OK
+
+``config`` is our configuration file that we pass on to ``start.py`` and as
+soon as a request is served we see the information from our ``after`` method.
+
+

docs/0.0.1/source/index.rst

@@ -43,7 +43,7 @@ framework!
 
 Pecan Hello World
 ------------------
-In this example we use ``httpserver`` from ``paste`` but feel free to use any 
+In this example we use ``httpserver`` from ``paste`` but you can use any 
 WSGI server you want::
 
     from paste import httpserver

docs/0.0.1/source/quick_start.rst

@@ -190,11 +190,14 @@ This is how it looks from the project template::
 Here you can specify other classes if you need to do so later on your project,
 but for now we have an *index* method and a *handle_form* one.
 
-**index**: Is *exposed* as the root of the application, so anything that hits
+**index**: Is *exposed* via the decorator ``@expose`` (that in turn uses the
+``index.html`` file) as the root of the application, so anything that hits
 '/' will touch this method.
 Since we are doing some validation and want to pass any errors we might get to
 the template, we set ``errors`` to receive anything that
 ``request.validation_error`` returns.
+What your index method returns is dictionary that is received by the template
+engine.
 
 
 **handle_form**: It receives 2 parameters (*name* and *age*) that are validated