Adding documentation for the debug middleware, including docstrings.

docs/source/development.rst

@@ -9,7 +9,37 @@ Reloading Automatically as Files Change
 
 Debugging Pecan Applications
 ----------------------------
-TODO
+Pecan comes with a simple debugging middleware for helping track down problems 
+in your applications. To enable the debugging middleware, simply set the
+``debug`` flag to ``True`` in your configuration file::
+
+    app = {
+        ...
+        'debug': True,
+        ...
+    }
+
+Once enabled, the middleware will automatically catch exceptions raised by your
+application, and display the Python stack trace and WSGI environment in your 
+browser for easy debugging.
+
+.. figure:: debug-middleware-1.png
+   :alt: Pecan debug middleware sample output.
+   :width: 90%
+   :align: center
+
+To further aid in debugging, the middleware includes the ability to repeat the
+offending request, automatically inserting a breakpoint, and dropping your
+console into the Python debugger, ``pdb``. 
+
+.. figure:: debug-middleware-2.png
+   :alt: Pecan debug middleware request debugger. 
+   :align: center
+
+For more information, refer to the  
+`documentation for pdb <http://docs.python.org/library/pdb.html>`_ available on
+the Python website.
+
 
 Serving Static Files
 --------------------

docs/source/index.rst

@@ -73,6 +73,7 @@ docstrings here:
    pecan_decorators.rst
    pecan_deploy.rst
    pecan_hooks.rst
+   pecan_middleware_debug.rst
    pecan_jsonify.rst
    pecan_rest.rst
    pecan_routing.rst

docs/source/pecan_middleware_debug.rst

@@ -0,0 +1,9 @@
+.. _pecan_middleware_debug:
+
+:mod:`pecan.middleware.debug` -- Pecan Debugging Middleware 
+===========================================================
+
+.. automodule:: pecan.middleware.debug
+  :members:
+  :show-inheritance:
+

pecan/middleware/debug.py

@@ -231,6 +231,35 @@ class PdbMiddleware(object):
 
 
 class DebugMiddleware(object):
+    """A WSGI middleware that provides debugging assistance for development
+    environments.
+
+    To enable the debugging middleware, simply set the ``debug`` flag to
+    ``True`` in your configuration file::
+
+        app = {
+            ...
+            'debug': True,
+            ...
+        }
+
+    Once enabled, the middleware will automatically catch exceptions raised by
+    your application, and display the Python stack trace and WSGI environment
+    in your browser for easy debugging.
+
+    To further aid in debugging, the middleware includes the ability to repeat
+    the offending request, automatically inserting a breakpoint, and dropping
+    your console into the Python debugger, ``pdb``.
+
+    For more information, refer to the  `documentation for pdb
+    <http://docs.python.org/library/pdb.html>`_ available on the Python
+    website.
+
+    :param app: the application to wrap.
+    :param debugger: a callable to start debugging, defaulting to the Python
+                     debugger, ``pdb``.
+    """
+
     def __init__(self, app, debugger=pdb.post_mortem):
         self.app = app
         self.debugger = debugger