Bringing docs up to date.

docs/source/configuration.rst

@@ -2,11 +2,10 @@
 
 Configuration
 =============
-Pecan is very easy to configure. As long as you follow certain conventions;
+Pecan is very easy to configure. As long as you follow certain conventions,
 using, setting and dealing with configuration should be very intuitive.
 
-Python files is what the framework uses to get the values from configuration
+Pecan configuration files are pure Python.  These files need to specify the values in a key/value way (Python
-files. These files need to specify the values in a key/value way (Python
 dictionaries) or if you need simple one-way values you can also specify them as
 direct variables (more on that below).
 
@@ -48,12 +47,14 @@ Things like debug mode, Root Controller and possible Hooks, should be specified
 here. This is what is used when the framework is wrapping your application into
 a valid WSGI app.
 
-A typical application configuration would look like this::
+A typical application configuration might look like this::
 
     app = {
-        'root' : RootController(),
+        'root' : 'project.controllers.root.RootController',
-        'static_root' : 'public', 
+        'modules' : ['project'],
-        'template_path' : 'project/templates',
+        'static_root'   : '%(confdir)s/public', 
+        'template_path' : '%(confdir)s/project/templates',
+        'reload' : True,
         'debug' : True 
     }
 
@@ -62,18 +63,22 @@ Let's look at each value and what it means:
 **app** is a reserved variable name for the configuration, so make sure you are
 not overriding, otherwise you will get default values.
 
-**root** Needs the Root Controller of your application. Remember that you are
+**root** The root controller of your application. Remember to provide
-passing an object instance, so you'll need to import it at the top of the file.
+a string representing a Python path to some callable (e.g.,
-In the example configuration, this would look something like::
+`yourapp.controllers.root.RootController`).
 
-    from myproject.controllers.root import RootController
+**static_root** Points to the directory where your static files live (relative
+to the project root).
 
-**static_root** Points to the directory where your static files live.
+**template_path** Points to the directory where your template files live
+(relative to the project root).
 
-**template_path** Points to the directory where your template files live.
+**reload** - When ``True``, ``pecan serve`` will listen for file changes and
+restare your app (especially useful for development).
 
-**debug** Enables ``WebError`` to have full tracebacks in the browser (this is
+**debug** Enables ``WebError`` to have display tracebacks in the browser 
-OFF by default).
+(**IMPORTANT**: Make sure this is *always* set to ``False`` in production
+environments).
 
 
 .. _server_configuration:
@@ -81,7 +86,7 @@ OFF by default).
 Server Configuration
 --------------------
 Pecan provides some defaults.  Change these to alter the host and port your
-WSGI app is served on.::
+WSGI app is served on::
 
     server = {
         'port' : '8080',
@@ -92,23 +97,18 @@ WSGI app is served on.::
 
 Accessing Configuration at Runtime 
 ----------------------------------
-You can access any configuration values at runtime via ``pecan.conf``.
+You can access any configuration value at runtime via ``pecan.conf``.
 This includes custom, application and server-specific values.
-Below is an example on how to access those values from your application::
 
-
+For example, if you needed to specify a global administrator, you could
-Custom and Single Values
-------------------------
-There might be times when you do not need a dictionary, but instead a simple
-value. For example, if you needed to specify a global administrator, you could
 do so like this within the configuration file::
 
     administrator = 'foo_bar_user'
 
-And it would be accessible in `pecan.conf` like::
+And it would be accessible in `pecan.conf` as::
 
-    >>>> from pecan import conf
+    >>> from pecan import conf
-    >>>> conf.administrator
+    >>> conf.administrator
     'foo_bar_user'
 
 

docs/source/installation.rst

@@ -13,7 +13,7 @@ Pecan can be isolated from other packages is best practice.
 To get started with an environment for Pecan, create a new
 `virtual environment <http://www.virtualenv.org>`_::
 
-    virtualenv --no-site-packages pecan-env
+    virtualenv pecan-env
     cd pecan-env 
     source bin/activate
 
@@ -31,12 +31,16 @@ After a lot of output, you should have Pecan successfully installed.
 Development (Unstable) Version
 ------------------------------
 If you want to run the development version of Pecan you will
-need to install git and clone the repo from github::
+need to install git and clone the repo from GitHub::
 
-    git clone https://github.com/pecan/pecan.git
+    git clone https://github.com/dreamhost/pecan.git
 
 If your virtual environment is still activated, call ``setup.py`` to install
 the development version::
 
     cd pecan
     python setup.py develop
+
+...alternatively, you can also install from GitHub directly with ``pip``::
+
+    pip install -e git://github.com/dreamhost/pecan.git#egg=pecan

docs/source/quick_start.rst

@@ -114,11 +114,7 @@ Simple Configuration
 --------------------
 For ease of use, Pecan configuration files are pure Python.
 
-This is how your default configuration file should look::
+This is how your default (generated) configuration file should look::
-
-    from test_project.controllers.root import RootController
-
-    import test_project
 
     # Server Specific Configurations
     server = {
@@ -128,8 +124,8 @@ This is how your default configuration file should look::
 
     # Pecan Application Configurations
     app = {
-        'root' : RootController(),
+        'root' : 'test_project.controllers.root.RootController',
-        'modules' : [test_project],
+        'modules' : ['test_project'],
         'static_root' : '%(confdir)s/public', 
         'template_path' : '%(confdir)s/test_project/templates',
         'reload': True,
@@ -162,9 +158,10 @@ Root Controller
 ---------------
 The Root Controller is the root of your application.
 
-This is how it looks in the project template::
+This is how it looks in the project template
+(``test_project.controllers.root.RootController``)::
 
-    from pecan import expose, request
+    from pecan import expose
     from formencode import Schema, validators as v
     from webob.exc import status_map
 
@@ -175,13 +172,23 @@ This is how it looks in the project template::
 
 
     class RootController(object):
-        @expose('index.html')
-        def index(self, name='', age=''):
-            return dict(errors=request.validation_errors, name=name, age=age)
 
-        @expose('success.html', schema=SampleForm(), error_handler='index')
+        @expose(
-        def handle_form(self, name, age):
+            generic     = True, 
-            return dict(name=name, age=age)
+            template    = 'index.html'
+        )
+        def index(self):
+            return dict()
+        
+        @index.when(
+            method          = 'POST',
+            template        = 'success.html',
+            schema          = SampleForm(),
+            error_handler   = '/index',
+            htmlfill        = dict(auto_insert_errors = True, prefix_error = False)
+        )
+        def index_post(self, name, age):
+            return dict(name=name)
         
         @expose('error.html')
         def error(self, status):
@@ -193,34 +200,32 @@ This is how it looks in the project template::
             return dict(status=status, message=message)
 
 
+You can specify additional classes and methods if you need to do so, but for 
+now we have an *index* and *index_post* method.
 
-You can specify additional classes if you need to do so, but for now we have an
+**def index**: is *exposed* via the decorator ``@expose`` (which in turn uses the
-*index* and *handle_form* method.
-
-**index**: is *exposed* via the decorator ``@expose`` (which in turn uses the
 ``index.html`` template) at the root of the application (http://127.0.0.1:8080/),
-so anything that hits the root of your application will touch this method.
+so any HTTP GET that hits the root of your application (/) will be routed to
+this method.
 
 Notice that the index method returns a dictionary - this dictionary is used as
 a namespace to render the specified template (``index.html``) into HTML.
 
-Since we are performing form validation and want to pass any errors we might
+**def index_post**: receives 2 arguments (*name* and *age*) that are validated
-get to the template, we set ``errors`` to receive form validation errors that
-may exist in ``request.validation_errors``.
-
-
-**handle_form**: receives 2 arguments (*name* and *age*) that are validated
 through the *SampleForm* schema.
 
+``method`` has been set to 'POST', so HTTP POSTs to the application root (in
+our example, form submissions) will be routed to this method.
+
 The ``error_handler`` has been set to index.  This means that when errors are
 raised, they will be sent to the index controller and rendered through its
 template.
 
-**error**: Finally, we have the error controller that allows your application to 
+**def error**: Finally, we have the error controller that allows your application to 
 display custom pages for certain HTTP errors (404, etc...).
 
 Application Interaction
 -----------------------
 If you still have your application running and you visit it in your browser,
-you should see a page with some information about Pecan and a form so you can
+you should see a page with some information about Pecan and the form so you can
 play a bit.

docs/source/routing.rst

@@ -3,11 +3,13 @@
 Routing
 =======
 
-When a user requests a Pecan-powered page how does Pecan know which
+When a user requests a certain URL in your app, how does Pecan know which
-controller to use? Pecan uses a method known as object-dispatch to map an
+controller to route to? Pecan uses a method known as **object-dispatch** to map an
 HTTP request to a controller. Object-dispatch begins by splitting the
 path into a list of components and then walking an object path, starting at
-the root controller. Let's look at a simple bookstore application: 
+the root controller. You can imagine your application's controllers as a tree
+of objects (branches of the object tree map directly to URL paths). Let's look 
+at a simple bookstore application: 
 
 ::