Improve documentation about config and app.py

Adds an explanation for app.modules in the app config, and documents
the requirements for the app.py file.

2 files changed, 18 insertions, 0 deletions

diff --git a/docs/source/configuration.rst b/docs/source/configuration.rst
index befefcc..84549a7 100644
--- a/docs/source/configuration.rst
+++ b/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"``).
diff --git a/docs/source/quick_start.rst b/docs/source/quick_start.rst
index 941c076..c35ce84 100644
--- a/docs/source/quick_start.rst
+++ b/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
 --------------------------