Reference zope.component docs on configuring eventsdocs

I'm working backwards from zopefoundation/zope.lifecycleevent#7
building up a chain of references :)

Also reorganize the main "usage" documentation for more narrative
readability. Make it the landing target for zope.event module
references.

5 files changed, 87 insertions, 42 deletions

diff --git a/docs/api.rst b/docs/api.rst
index f21b7dc..f7f79ec 100644
--- a/docs/api.rst
+++ b/docs/api.rst
@@ -1,17 +1,18 @@
 .. _api-docs:
 
-:mod:`zope.event` API Reference
-===============================
+=================================
+ :mod:`zope.event` API Reference
+=================================
 
 The package exports the following API symbols.
 
 Data
-----
+====
 
 .. autodata:: zope.event.subscribers
 
 
 Functions
----------
-   
+=========
+
 .. autofunction:: zope.event.notify
diff --git a/docs/classhandler.rst b/docs/classhandler.rst
index 936735c..94861b2 100644
--- a/docs/classhandler.rst
+++ b/docs/classhandler.rst
@@ -1,5 +1,6 @@
-Class-based event handlers
-==========================
+============================
+ Class-based event handlers
+============================
 
 A light-weight event-handler framework based on event classes is
 provided by the ``zope.event.classhandler`` module.
@@ -39,4 +40,3 @@ new-style event classes are supported, and then by order of registry.
     handler3 MySubEvent
     handler1 MySubEvent
     handler2 MySubEvent
-
diff --git a/docs/index.rst b/docs/index.rst
index 0d5be8b..8983eb9 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -1,8 +1,13 @@
-:mod:`zope.event` Documentation
-===============================
+=================================
+ :mod:`zope.event` Documentation
+=================================
 
 This package provides a simple event system on which
-application-specific event systems can be built.
+application-specific event systems can be built. For example, a
+type-based event dispatching system that builds on `zope.interface
+<https://zopeinterface.readthedocs.io/en/latest/>`_ can be found in
+`zope.component <https://zopecomponent.readthedocs.io/en/latest>`_. A
+simpler system is distributed with this package and is described in :doc:`classhandler`.
 
 Application code can generate events without being concerned about the
 event-processing frameworks that might handle the events.
@@ -22,8 +27,9 @@ Contents:
    classhandler
    hacking
 
-Indices and tables
-==================
+====================
+ Indices and tables
+====================
 
 * :ref:`genindex`
 * :ref:`modindex`
diff --git a/docs/usage.rst b/docs/usage.rst
index 726628d..29e6b8a 100644
--- a/docs/usage.rst
+++ b/docs/usage.rst
@@ -1,50 +1,92 @@
 .. _usage-docs:
 
-Using :mod:`zope.event`
-=======================
+=========================
+ Using :mod:`zope.event`
+=========================
 
-The :mod:`zope.event` package has a list of subscribers.  Application code
-can manage subscriptions by manipulating this list.  For the examples here,
-we'll save the current contents away and empty the list. We'll restore the
-contents when we're done with our examples.
+.. py:module:: zope.event
 
-.. doctest::
+At its core, :mod:`zope.event` simply consists of two things: a list
+of subscribers (callable objects), and an API function
+(:func:`~.zope.event.notify`) that invokes those subscribers in order.
 
-  >>> import zope.event
-  >>> old_subscribers = zope.event.subscribers[:]
-  >>> del zope.event.subscribers[:]
+.. testsetup::
+
+  import zope.event
+  old_subscribers = zope.event.subscribers[:]
+  del zope.event.subscribers[:]
 
-The package provides a :func:`notify` function, which is used to
+Notifications
+=============
+
+Alerting subscribers that an event has occurred is referred to as
+"notifying them", or sometimes "sending them the event."
+
+The package provides a :func:`~.zope.event.notify` function, which is used to
 notify subscribers that something has happened:
 
 .. doctest::
 
-  >>> class MyEvent:
+  >>> class MyEvent(object):
   ...     pass
 
   >>> event = MyEvent()
   >>> zope.event.notify(event)
 
 The notify function is called with a single object, which we call an
-event.  Any object will do:
+event. Any object will do:
 
 .. doctest::
 
   >>> zope.event.notify(None)
   >>> zope.event.notify(42)
 
-An extremely trivial subscription mechanism is provided. Subscribers
-are simply callback functions:
+Our subscriber list is currently empty, so nothing happened in
+response to these notifications.
+
+Subscribers
+===========
+
+A *subscriber* is a callable object that takes one argument, an object
+that we call the *event*.
+
+Application code can manage subscriptions by manipulating the list
+that ``zope.event`` maintains. This list starts out empty.
 
 .. doctest::
 
-  >>> def f(event):
-  ...     print 'got:', event
+  >>> import zope.event
+  >>> zope.event.subscribers
+  []
+
 
-that are put into the subscriptions list:
+.. note:: Users of higher-level event frameworks will not typically
+   need to modify *this* subscriber list directly. Generally, such event
+   (or application) frameworks will provide more sophisticated
+   subscription mechanisms that build on this simple mechanism. The
+   frameworks will install subscribers that then distribute the event to other
+   subscribers based on event types or data.
+
+   A simple framework that is based on the class hierarchy is
+   distributed with this package and described in :doc:`classhandler`.
+
+   A higher-level event framework is distributed with
+   :mod:`zope.component`. For information on using :mod:`zope.event`
+   together with :mod:`zope.component`, see `zope.component's
+   documentation
+   <http://zopecomponent.readthedocs.io/en/latest/event.html>`_.
+
+
+Trivial Subscribers
+-------------------
+
+As mentioned above, subscribers are simply callable objects that are
+added to the subscriptions list:
 
 .. doctest::
 
+  >>> def f(event):
+  ...     print 'got:', event
   >>> zope.event.subscribers.append(f)
 
   >>> zope.event.notify(42)
@@ -67,14 +109,9 @@ To unsubscribe, simply remove a subscriber from the list:
   >>> zope.event.notify(42)
   also got: 42
 
-Generally, application frameworks will provide more sophisticated
-subscription mechanisms that build on this simple mechanism. The
-frameworks will install subscribers that then dispatch to other
-subscribers based on event types or data.
-
-We're done, so we'll restore the subscribers:
-
-.. doctest::
+  >>> zope.event.subscribers.remove(g)
+  >>> zope.event.notify(42)
 
-  >>> zope.event.subscribers[:] = old_subscribers
+.. testcleanup::
 
+  zope.event.subscribers[:] = old_subscribers
diff --git a/src/zope/event/__init__.py b/src/zope/event/__init__.py
index e335696..8eaf9bf 100644
--- a/src/zope/event/__init__.py
+++ b/src/zope/event/__init__.py
@@ -17,11 +17,12 @@
 
 #: Applications may register for notification of events by appending a
 #: callable to the ``subscribers`` list.
-#: 
+#:
 #: Each subscriber takes a single argument, which is the event object
 #: being published.
 #:
-#: Exceptions raised by subscribers will be propagated.
+#: Exceptions raised by subscribers will be propagated *without* running
+#: any remaining subscribers.
 subscribers = []
 
 def notify(event):