From a0423aedb4abaf12b4008c0b229ec0ecad4ddfd8 Mon Sep 17 00:00:00 2001
From: Chris McDonough <chrism@agendaless.com>
Date: Thu, 31 Jul 2008 06:17:31 +0000
Subject:   - Add event sends for INewRequest and INewResponse.  See the    
 events.rst chapter in the documentation's ``api`` directory.

---
 docs/api/events.rst | 49 +++++++++++++++++++++++++++++++++++++++++++++++++
 docs/conf.py        |  4 ++--
 docs/index.rst      |  1 +
 3 files changed, 52 insertions(+), 2 deletions(-)
 create mode 100644 docs/api/events.rst

(limited to 'docs')

diff --git a/docs/api/events.rst b/docs/api/events.rst
new file mode 100644
index 000000000..25bb9841b
--- /dev/null
+++ b/docs/api/events.rst
@@ -0,0 +1,49 @@
+.. _events_module:
+
+:mod:`repoze.bfg.events`
+--------------------------
+
+.. automodule:: repoze.bfg.events
+
+  .. autoclass:: NewRequest
+
+  .. autoclass:: NewResponse
+
+You can write *listeners* for these event types and subsequently
+register the listeners to be called when the events occur.  For
+example, if you create event listener functions in a ``listeners.py``
+file in your application like so:
+
+.. code-block:: python
+   :linenos:
+
+   def handle_new_request(event):
+       print 'request', event.request   
+
+   def handle_new_response(event):
+       print 'response', event.response
+
+You may configure these functions to be called at the appropriate
+times by adding the following to your application's ``configure.zcml``
+file:
+
+.. code-block:: xml
+   :linenos:
+
+   <subscriber
+      for="repoze.bfg.interfaces.INewRequest"
+      handler=".listeners.handle_new_request"
+    />
+
+   <subscriber
+      for="repoze.bfg.interfaces.INewResponse"
+      handler=".listeners.handle_new_response"
+    />
+
+This causes the functions as to be registered as event listeners
+within the :term:`application registry` .  Under this configuration,
+when the application is run, every new request and every response will
+be printed to the console.
+
+The return value of a listener function is ignored.
+
diff --git a/docs/conf.py b/docs/conf.py
index 8d19cf4db..2a0d53381 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -51,9 +51,9 @@ copyright = '2008, Agendaless Consulting'
 # other places throughout the built documents.
 #
 # The short X.Y version.
-version = '0.2.5'
+version = '0.2.6'
 # The full version, including alpha/beta/rc tags.
-release = '0.2.5'
+release = '0.2.6'
 
 # There are two options for replacing |today|: either, you set today to some
 # non-false value, then it is used:
diff --git a/docs/index.rst b/docs/index.rst
index 5825a6129..63f8b96e4 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -50,6 +50,7 @@ Per-module :mod:`repoze.bfg` API documentation.
 .. toctree::
    :maxdepth: 2
 
+   api/events
    api/push
    api/router
    api/security
-- 
cgit v1.2.3