break out 'extending config' into exconfig and add stuff about the action method; move startup and router chapters to earlier in toc

1 files changed, 2 insertions, 75 deletions

diff --git a/docs/narr/advconfig.rst b/docs/narr/advconfig.rst
index 3b6f7669a..3a7bf2805 100644
--- a/docs/narr/advconfig.rst
+++ b/docs/narr/advconfig.rst
@@ -13,8 +13,6 @@ also, by default, performs configuration in two separate phases.  This allows
 you to ignore relative configuration statement ordering in some
 circumstances.
 
-Pyramid also allows you to extend its Configurator with custom directives.
-
 .. index::
    pair: configuration; conflict detection
 
@@ -117,6 +115,8 @@ Conflict detection happens for any kind of configuration: imperative
 configuration or configuration that results from the execution of a
 :term:`scan`.
 
+.. _manually_resolving_conflicts:
+
 Manually Resolving Conflicts
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -399,76 +399,3 @@ 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.
 
-.. index::
-   single: add_directive
-   pair: configurator; adding directives
-
-.. _add_directive:
-
-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)