Merge pull request #148 from berler/next

Improved Documentation

docs/source/configuration.rst

@@ -49,6 +49,15 @@ Let's look at each value and what it means:
 **app** is a reserved variable name for the configuration, so make sure you
 don't override it.
 
+**modules** is a list of modules where pecan will search for applications.
+Generally this should contain a single item, the name of your project's
+python package.
+At least one of the listed modules must contain an ``app.setup_app`` function
+which is called to create the WSGI app.  In other words, this package should
+be where your ``app.py`` file is located, and this file should contain a
+``setup_app`` function.
+See :ref:`app_template` for more about the ``app.py`` file.
+
 **root** The root controller of your application. Remember to provide
 a string representing a Python path to some callable (e.g.,
 ``"yourapp.controllers.root.RootController"``).

docs/source/quick_start.rst

@@ -9,6 +9,7 @@ Let's create a small sample project with Pecan.
     This guide does not cover the installation of Pecan. If you need
     instructions for installing Pecan, go to :ref:`installation`.
 
+.. _app_template:
 
 Base Application Template
 -------------------------
@@ -76,6 +77,13 @@ remaining directories encompass your models, controllers and templates...
 
 *  **test_project/tests**:        All of the tests for your application.
 
+The **test_project/app.py** file controls how the Pecan application will be
+created. This file must contain a ``setup_app`` function which returns the
+WSGI application object.  Generally you will not need to modify the ``app.py``
+file provided by the base application template unless you need to customize
+your app in a way that cannot be accomplished using config.  See
+:ref:`python_based_config` below.
+
 To avoid unneeded dependencies and to remain as flexible as possible, Pecan
 doesn't impose any database or ORM 
 (`Object Relational Mapper
@@ -111,6 +119,7 @@ configuration, it will bring up the development server and serve the app::
 The location for the configuration file and the argument itself are very
 flexible - you can pass an absolute or relative path to the file.
 
+.. _python_based_config:
 
 Python-Based Configuration
 --------------------------

pecan/__init__.py

@@ -27,7 +27,33 @@ __all__ = [
 
 def make_app(root, static_root=None, logging={}, debug=False,
              wrap_app=None, **kw):
+    '''
+    Utility for creating the Pecan application object.  This function should
+    generally be called from the ``setup_app`` function in your project's
+    ``app.py`` file.
 
+    :param root: A string representing a root controller object (e.g.,
+                 "myapp.controller.root.RootController")
+    :param static_root: The relative path to a directory containing static
+                        files.  Serving static files is only enabled when
+                        debug mode is set.
+    :param logging: A dictionary used to configure logging.  This uses
+                    ``logging.config.dictConfig``.
+    :param debug: A flag to enable debug mode.  This enables the debug
+                  middleware and serving static files.
+    :param wrap_app: A function or middleware class to wrap the Pecan app.
+                     This must either be a wsgi middleware class or a
+                     function that returns a wsgi application. This wrapper
+                     is applied first before wrapping the application in
+                     other middlewares such as Pecan's debug middleware.
+                     This should be used if you want to use middleware to
+                     perform authentication or intercept all requests before
+                     they are routed to the root controller.
+
+    All other keyword arguments are passed in to the Pecan app constructor.
+
+    :returns: a ``Pecan`` object.
+    '''
     # A shortcut for the RequestViewerHook middleware.
     if hasattr(conf, 'requestviewer'):
         existing_hooks = kw.get('hooks', [])