- Added "Adding Methods to the Configurator via ``add_directive``" section to

  Advanced Configuration narrative chapter.

4 files changed, 79 insertions, 11 deletions

diff --git a/CHANGES.txt b/CHANGES.txt
index 8df963aac..5c0a90d4d 100644
--- a/CHANGES.txt
+++ b/CHANGES.txt
@@ -18,6 +18,9 @@ Documentation
 - Fix deprecated example showing ``chameleon_zpt`` API call in testing
   narrative chapter.
 
+- Added "Adding Methods to the Configurator via ``add_directive``" section to
+  Advanced Configuration narrative chapter.
+
 Deprecations
 -------------
 
diff --git a/TODO.txt b/TODO.txt
index 5b78e2a74..80e700c00 100644
--- a/TODO.txt
+++ b/TODO.txt
@@ -22,6 +22,13 @@ Must-Have (before 1.0)
 - Add docs for ``route_path`` and ``route_url``, etc to Request API docs (see
   also https://github.com/Pylons/pyramid/issues#issue/19).
 
+- Add example for ``__action_decorator__`` to pyramid_handler docs.
+
+- Figure out what to do with "Forms" chapter in narr docs.
+
+Should-Have
+-----------
+
 - Reversing (context, request) in function view callable arglist produces
   incomprehensible traceback::
 
@@ -42,15 +49,6 @@ Must-Have (before 1.0)
    zope.configuration.config.ConfigurationExecutionError: <type 'exceptions.TypeError'>: object of type 'NoneType' has no len()                                    in:
     ('reversed.py', 14, '<module>', "c.add_view(aview, renderer='__main__:foo.pt')")
 
-- Document ``add_directive``.
-
-- Add example for ``__action_decorator__`` to pyramid_handler docs.
-
-- Figure out what to do with "Forms" chapter in narr docs.
-
-Should-Have
------------
-
 - Fix misleading conflict error reports for static views ala
   http://cluebin.appspot.com/pasted/7242843
 
diff --git a/docs/api/config.rst b/docs/api/config.rst
index 05bcb8146..4b5f1fa21 100644
--- a/docs/api/config.rst
+++ b/docs/api/config.rst
@@ -28,6 +28,8 @@
 
      .. automethod:: include
 
+     .. automethod:: add_directive
+
      .. automethod:: with_package
 
      .. automethod:: maybe_dotted
@@ -72,8 +74,6 @@
 
      .. automethod:: set_renderer_globals_factory
 
-     .. automethod:: add_directive
-
      .. automethod:: testing_securitypolicy
 
      .. automethod:: testing_resources
diff --git a/docs/narr/advconfig.rst b/docs/narr/advconfig.rst
index 30f76e456..1cdf1e945 100644
--- a/docs/narr/advconfig.rst
+++ b/docs/narr/advconfig.rst
@@ -403,3 +403,70 @@ constraints: the routes they imply require relative ordering.  Such ordering
 constraints are not absolved by two-phase configuration.  Routes are still
 added in configuration execution order.
 
+Adding Methods to the Configurator via ``add_directive``
+--------------------------------------------------------
+
+Framework extension writers can add arbitrary methods to a
+:term:`Configurator` by using the
+:meth:`pyramid.config.Configurator.add_directive` method of the configurator.
+This makes it possible to extend a Pyramid configurator in arbitrary ways,
+and allows it to perform application-specific tasks more succinctly.
+
+The :meth:`~pyramid.config.Configurator.add_directive` method accepts two
+positional arguments: a method name and a callable object.  The callable
+object is usually a function that takes the configurator instance as its
+first argument and accepts other arbitrary positional and keyword arguments.
+For example:
+
+.. code-block:: python
+   :linenos:
+
+   from pyramid.events import NewRequest
+   from pyramid.config import Configurator
+
+   def add_newrequest_subscriber(config, subscriber):
+       config.add_subscriber(subscriber, NewRequest).
+
+   if __name__ == '__main__':
+      config = Configurator()
+      config.add_directive('add_newrequest_subscriber', 
+                           add_newrequest_subscriber)
+
+Once :meth:`~pyramid.config.Configurator.add_directive` is called, a user can
+then call the method by its given name as if it were a built-in method of the
+Configurator:
+
+.. code-block:: python
+   :linenos:
+
+   def mysubscriber(event):
+      print event.request
+
+   config.add_newrequest_subscriber(mysubscriber)
+
+A call to :meth:`~pyramid.config.Configurator.add_directive` is often
+"hidden" within an ``includeme`` function within a "frameworky" package meant
+to be included as per :ref:`including_configuration` via
+:meth:`~pyramid.config.Configurator.include`.  For example, if you put this
+code in a package named ``pyramid_subscriberhelpers``:
+
+.. code-block:: python
+   :linenos:
+
+   def includeme(config)
+      config.add_directive('add_newrequest_subscriber', 
+                           add_newrequest_subscriber)
+
+The user of the add-on package ``pyramid_subscriberhelpers`` would then be
+able to install it and subsequently do:
+
+.. code-block:: python
+   :linenos:
+
+   def mysubscriber(event):
+      print event.request
+
+   from pyramid.config import Configurator
+   config = Configurator()
+   config.include('pyramid_subscriberhelpers')
+   config.add_newrequest_subscriber(mysubscriber)