- event documentation bonanza

4 files changed, 44 insertions, 86 deletions

diff --git a/doc/build/core/event.rst b/doc/build/core/event.rst
index 946aa7901..aae7a727e 100644
--- a/doc/build/core/event.rst
+++ b/doc/build/core/event.rst
@@ -8,8 +8,6 @@ the internals of both SQLAlchemy Core and ORM.   The system is all new
 as of version 0.7 and supercedes the previous system of "extension", "proxy", 
 and "listener" classes.
 
-Core events are described in :ref:`core_event_toplevel` and ORM events in :ref:`orm_event_toplevel`.
-
 Event Registration
 ------------------
 
@@ -21,7 +19,7 @@ instructions regarding secondary event targets based on the given target.
 
 The name of an event and the argument signature of a corresponding listener function is derived from 
 a class bound specification method, which exists bound to a marker class that's described in the documentation.
-For example, the documentation for :ref:`.PoolEvents.on_connect` indicates that the event name is ``"on_connect"``
+For example, the documentation for :meth:`.PoolEvents.on_connect` indicates that the event name is ``"on_connect"``
 and that a user-defined listener function should receive two positional arguments::
 
     from sqlalchemy.event import listen
@@ -82,6 +80,25 @@ which modifies the subsequent handling.   By default, no listener ever requires
     # it to use the return value
     listen(validate_phone, 'on_set', UserContact.phone, retval=True)
 
- 
+Event Reference
+----------------
+
+Both SQLAlchemy Core and SQLAlchemy ORM feature a wide variety of event hooks:
+
+* **Core Events** - these are described in
+  :ref:`core_event_toplevel` and include event hooks specific to
+  connection pool lifecycle, SQL statement execution,
+  transaction lifecycle, and schema creation and teardown.
+  
+* **ORM Events** - these are described in
+  :ref:`orm_event_toplevel`, and include event hooks specific to
+  class and attribute instrumentation, object initialization
+  hooks, attribute on-change hooks, session state, flush, and
+  commit hooks, mapper initialization, object/result population,
+  and per-instance persistence hooks.
+
+API Reference
+-------------
+
 .. autofunction:: sqlalchemy.event.listen
 
diff --git a/doc/build/core/events.rst b/doc/build/core/events.rst
index 7f0d2d530..6c8b4d064 100644
--- a/doc/build/core/events.rst
+++ b/doc/build/core/events.rst
@@ -3,8 +3,12 @@
 Core Events
 ============
 
-This section describes the event interfaces provided in SQLAlchemy Core.  For an introduction
-to the event listening API, see :ref:`event_toplevel`.   ORM events are described in :ref:`orm_event_toplevel`.
+This section describes the event interfaces provided in
+SQLAlchemy Core. The event system in 0.7 is all new and
+supercedes the previous system of "extension", "listener", and
+"proxy" classes. For an introduction to the event listening API,
+see :ref:`event_toplevel`. ORM events are described in
+:ref:`orm_event_toplevel`.
 
 Connection Pool Events
 -----------------------
diff --git a/doc/build/orm/events.rst b/doc/build/orm/events.rst
index 87dbe5d7d..fdbe3d339 100644
--- a/doc/build/orm/events.rst
+++ b/doc/build/orm/events.rst
@@ -5,7 +5,9 @@ ORM Events
 
 The ORM includes a wide variety of hooks available for subscription.  The event
 system in 0.7 is all new and supercedes the previous system of "extension" classes.
-For an introduction to the event API, see :ref:`core_event_toplevel`.
+For an introduction to the event API, see :ref:`event_toplevel`.  Non-ORM events
+such as those regarding connections and low-level statement execution are described in 
+:ref:`core_event_toplevel`.
 
 Attribute Events
 ----------------
@@ -13,12 +15,6 @@ Attribute Events
 .. autoclass:: sqlalchemy.orm.events.AttributeEvents
    :members:
 
-Instrumentation Events
------------------------
-
-.. autoclass:: sqlalchemy.orm.events.InstrumentationEvents
-   :members:
-
 Mapper Events
 ---------------
 
@@ -36,3 +32,17 @@ Session Events
 
 TODO
 
+Instrumentation Events
+-----------------------
+
+.. autoclass:: sqlalchemy.orm.events.InstrumentationEvents
+   :members:
+
+Alternate Class Instrumentation
+-------------------------------
+
+.. autoclass:: sqlalchemy.orm.interfaces.InstrumentationManager
+    :members:
+    :undoc-members:
+
+
diff --git a/doc/build/orm/interfaces.rst b/doc/build/orm/interfaces.rst
index 3d19f0f40..0df54cfda 100644
--- a/doc/build/orm/interfaces.rst
+++ b/doc/build/orm/interfaces.rst
@@ -16,91 +16,18 @@ a consistent interface to all events without the need for subclassing.
 Mapper Events
 -----------------
 
-To use :class:`.MapperExtension`, make your own subclass of it and just send it off to a mapper::
-    
-    from sqlalchemy.orm.interfaces import MapperExtension
-    
-    class MyExtension(MapperExtension):
-        def before_insert(self, mapper, connection, instance):
-            print "instance %s before insert !" % instance
-    
-    m = mapper(User, users_table, extension=MyExtension())
-
-Multiple extensions will be chained together and processed in order; they are specified as a list::
-
-    m = mapper(User, users_table, extension=[ext1, ext2, ext3])
-
 .. autoclass:: MapperExtension
     :members:
 
 Session Events
 -----------------
 
-The :class:`.SessionExtension` applies plugin points for :class:`.Session` objects::
-
-    from sqlalchemy.orm.interfaces import SessionExtension
-    
-    class MySessionExtension(SessionExtension):
-        def before_commit(self, session):
-            print "before commit!"
-
-    Session = sessionmaker(extension=MySessionExtension())
-
-The same :class:`~sqlalchemy.orm.interfaces.SessionExtension` instance can be
-used with any number of sessions.
-
 .. autoclass:: SessionExtension
     :members:
 
 Attribute Events
 --------------------
 
-:class:`.AttributeExtension` is used to listen for set, remove, and append
-events on individual mapped attributes. It is established on an individual
-mapped attribute using the `extension` argument, available on
-:func:`.column_property`, :func:`.relationship`, and others::
-
-    from sqlalchemy.orm.interfaces import AttributeExtension
-    from sqlalchemy.orm import mapper, relationship, column_property
-    
-    class MyAttrExt(AttributeExtension):
-        def append(self, state, value, initiator):
-            print "append event !"
-            return value
-        
-        def set(self, state, value, oldvalue, initiator):
-            print "set event !"
-            return value
-            
-    mapper(SomeClass, sometable, properties={
-        'foo':column_property(sometable.c.foo, extension=MyAttrExt()),
-        'bar':relationship(Bar, extension=MyAttrExt())
-    })
-
-Note that the :class:`AttributeExtension` methods
-:meth:`~.AttributeExtension.append` and :meth:`~.AttributeExtension.set` need
-to return the ``value`` parameter. The returned value is used as the effective
-value, and allows the extension to change what is ultimately persisted.
-
 .. autoclass:: AttributeExtension
     :members:
 
-Instrumentation Events and Re-implementation
----------------------------------------------
-
-:class:`.InstrumentationManager` can be subclassed in order to receive class
-instrumentation events as well as to change how class instrumentation
-proceeds. This class exists for the purposes of integration with other object
-management frameworks which would like to entirely modify the instrumentation
-methodology of the ORM, and is not intended for regular usage. One possible
-exception is the :meth:`.InstrumentationManager.post_configure_attribute`
-method, which can be useful for adding extensions to all mapped attributes,
-though a much better way to do this will be available in a future release of
-SQLAlchemy.
-
-For an example of :class:`.InstrumentationManager`, see the example
-:ref:`examples_instrumentation`.
-
-.. autoclass:: InstrumentationManager
-    :members:
-    :undoc-members: