- merged -r5338:5429 of sphinx branch.

- Documentation has been converted to Sphinx.
In particular, the generated API documentation
has been constructed into a full blown
"API Reference" section which organizes
editorial documentation combined with
generated docstrings.   Cross linking between
sections and API docs are vastly improved,
a javascript-powered search feature is
provided, and a full index of all
classes, functions and members is provided.

1 files changed, 7 insertions, 3 deletions

diff --git a/lib/sqlalchemy/interfaces.py b/lib/sqlalchemy/interfaces.py
index ae92dc50d..f9c21d246 100644
--- a/lib/sqlalchemy/interfaces.py
+++ b/lib/sqlalchemy/interfaces.py
@@ -12,6 +12,11 @@ class PoolListener(object):
 
     Usage::
     
+        class MyListener(PoolListener):
+            def connect(self, dbapi_con, con_record):
+                '''perform connect operations'''
+            # etc. 
+            
         # create a new pool with a listener
         p = QueuePool(..., listeners=[MyListener()])
         
@@ -19,10 +24,9 @@ class PoolListener(object):
         p.add_listener(MyListener())
         
         # usage with create_engine()
-        e = create_engine("url://", ...)
-        e.pool.add_listener(MyListener())
+        e = create_engine("url://", listeners=[MyListener()])
         
-    All of the standard connection [sqlalchemy.pool#Pool] types can
+    All of the standard connection :class:`~sqlalchemy.pool.Pool` types can
     accept event listeners for key connection lifecycle events:
     creation, pool check-out and check-in.  There are no events fired
     when a connection closes.