fix merge conflict

8 files changed, 40 insertions, 80 deletions

diff --git a/docs/narr/advconfig.rst b/docs/narr/advconfig.rst
index f8b3ee191..eb9b70b12 100644
--- a/docs/narr/advconfig.rst
+++ b/docs/narr/advconfig.rst
@@ -301,9 +301,6 @@ These are the methods of the configurator which provide conflict detection:
 Some other methods of the configurator also indirectly provide conflict
 detection, because they're implemented in terms of conflict-aware methods:
 
-- :meth:`~pyramid.config.Configurator.add_handler`, a frontend for
-  ``add_route`` and ``add_view``.
-
 - :meth:`~pyramid.config.Configurator.add_route` does a second type of
   conflict detection when a ``view`` parameter is passed (it calls
   ``add_view``).
@@ -338,6 +335,23 @@ Instead, use :meth:`pyramid.config.Configuration.include`:
 Using ``include`` rather than calling the function directly will allow
 :ref:`automatic_conflict_resolution` to work.
 
+:meth:`pyramid.config.Configuration.include` can also accept a :term:`module`
+as an argument:
+
+.. code-block:: python
+   :linenos:
+
+   import myapp
+
+   config.include(myapp)
+
+For this to work properly, the ``myapp`` module must contain a callable with
+the special name ``includeme``, which should perform configuration (like the
+``add_routes`` callable we showed above as an example).
+
+:meth:`pyramid.config.Configuration.include` can also accept a :term:`dotted
+Python name` to a function or a module.
+
 .. note: See :ref:`the_include_tag` for a declarative alternative to
    :meth:`pyramid.config.Configurator.include`.
 
@@ -387,8 +401,7 @@ used, two-phase configuration is disabled, and configuration statements must
 be ordered in dependency order.
 
 Some configuration methods, such as
-:meth:`pyramid.config.Configurator.add_route` and
-:meth:`pyramid.config.Configurator.add_handler` have internal ordering
+:meth:`pyramid.config.Configurator.add_route` have internal ordering
 constraints: they routes they imply require relative ordering.  Such ordering
 constraints are not absolved by two-phase configuration.  Routes are still
 added in configuration execution order.
diff --git a/docs/narr/assets.rst b/docs/narr/assets.rst
index f73ff231a..b1c1c419c 100644
--- a/docs/narr/assets.rst
+++ b/docs/narr/assets.rst
@@ -345,7 +345,7 @@ application's startup code.
 .. code-block:: python
    :linenos:
 
-   # .. every other add_route and/or add_handler declaration should come
+   # .. every other add_route declaration should come
    # before this one, as it will, by default, catch all requests
 
    config.add_route('catchall_static', '/*subpath', 'myapp.static.static_view')
diff --git a/docs/narr/declarative.rst b/docs/narr/declarative.rst
index 5c731ab06..5c01ff491 100644
--- a/docs/narr/declarative.rst
+++ b/docs/narr/declarative.rst
@@ -704,46 +704,6 @@ is the order that they appear relative to each other in the ZCML file.
 See :ref:`route_directive` for full ``route`` ZCML directive
 documentation.
 
-.. _zcml_handler_configuration:
-
-Configuring a Handler via ZCML
-------------------------------
-
-Instead of using the imperative
-:meth:`pyramid.config.Configurator.add_handler` method to add a new
-route, you can alternately use :term:`ZCML`.  :ref:`handler_directive`
-statements in a :term:`ZCML` file used by your application is a sign that
-you're using :term:`URL dispatch`.  For example, the following :term:`ZCML
-declaration` causes a route to be added to the application.
-
-.. code-block:: xml
-   :linenos:
-
-   <handler
-     route_name="myroute"
-     pattern="/prefix/{action}"
-     handler=".handlers.MyHandler"
-    />
-
-.. note::
-
-   Values prefixed with a period (``.``) within the values of ZCML attributes
-   such as the ``handler`` attribute of a ``handler`` directive mean
-   "relative to the Python package directory in which this :term:`ZCML` file
-   is stored".  So if the above ``handler`` declaration was made inside a
-   ``configure.zcml`` file that lived in the ``hello`` package, you could
-   replace the relative ``.views.MyHandler`` with the absolute
-   ``hello.views.MyHandler`` Either the relative or absolute form is
-   functionally equivalent.  It's often useful to use the relative form, in
-   case your package's name changes.  It's also shorter to type.
-
-The order that the routes attached to handlers are evaluated when declarative
-configuration is used is the order that they appear relative to each other in
-the ZCML file.
-
-See :ref:`handler_directive` for full ``handler`` ZCML directive
-documentation.
-
 .. index::
    triple: view; zcml; static resource
 
diff --git a/docs/narr/extending.rst b/docs/narr/extending.rst
index 524dcb2ac..eb7f0b24e 100644
--- a/docs/narr/extending.rst
+++ b/docs/narr/extending.rst
@@ -121,9 +121,9 @@ ZCML ``<route>`` directive).  Views are declarations made using the
 directive).  Assets are files that are accessed by :app:`Pyramid` using the
 :term:`pkg_resources` API such as static files and templates via a
 :term:`asset specification`.  Other directives and configurator methods also
-deal in routes, views, and assets.  For example,
-:meth:`pyramid.config.Configurator.add_handler` adds a single route, and some
-number of views.
+deal in routes, views, and assets.  For example, ``add_handler`` directive of
+the ``pyramid_handlers`` package adds a single route, and some number of
+views.
 
 .. index::
    single: extending an existing application
diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst
index c12a5abb4..96515c195 100644
--- a/docs/narr/hooks.rst
+++ b/docs/narr/hooks.rst
@@ -611,6 +611,7 @@ A user might make use of these framework components like so:
 
    from webob import Response
    from pyramid.config import Configurator
+   import pyramid_handlers
    from paste.httpserver import serve
 
    class MyController(BaseController):
@@ -619,6 +620,7 @@ A user might make use of these framework components like so:
 
    if __name__ == '__main__':
        config = Configurator()
+       config.include(pyramid_handlers)
        config.add_handler('one', '/{id}', MyController, action='index')
        config.add_handler('two', '/{action}/{id}', MyController)
        serve(config.make_wsgi_app())
diff --git a/docs/narr/project.rst b/docs/narr/project.rst
index 46de560c2..a76a8ce51 100644
--- a/docs/narr/project.rst
+++ b/docs/narr/project.rst
@@ -30,9 +30,6 @@ and so therefore they are often referred to as "paster templates".
    single: pyramid_zodb paster template
    single: pyramid_alchemy paster template
    single: pyramid_routesalchemy paster template
-   single: pylons_minimal paster template
-   single: pylons_basic paster template
-   single: pylons_sqla paster template
 
 .. _additional_paster_templates:
 
@@ -74,20 +71,6 @@ The included templates are these:
   URL mapping via :term:`traversal` and persistence via
   :term:`SQLAlchemy`
 
-``pylons_minimal``
-  URL mapping via :term:`URL dispatch` and Pylons-style view handlers,
-  minimal setup, uses ``pyramid_beaker`` as a sessioning implementation.
-
-``pylons_basic``
-  URL mapping via :term:`URL dispatch` and Pylons-style view handlers, and
-  some extra functionality, uses ``pyramid_beaker`` as a sessioning
-  implementation.
-
-``pylons_sqla``
-  URL mapping via :term:`URL dispatch` and Pylons-style view handlers, some
-  extra functionality, and SQLAlchemy set up, uses ``pyramid_beaker`` as a
-  sessioning implementation.
-
 .. index::
    single: creating a project
    single: project
@@ -965,10 +948,10 @@ To this:
                     renderer='myproject:templates/mytemplate.pt')
 
 You can then continue to add files to the ``views`` directory, and refer to
-views or handler classes/functions within those files via the dotted name
-passed as the first argument to ``add_view``.  For example, if you added a
-file named ``anothermodule.py`` to the ``views`` subdirectory, and added a
-view callable named ``my_view`` to it:
+view classes or functions within those files via the dotted name passed as
+the first argument to ``add_view``.  For example, if you added a file named
+``anothermodule.py`` to the ``views`` subdirectory, and added a view callable
+named ``my_view`` to it:
 
 .. code-block:: python
     :linenos:
diff --git a/docs/narr/viewconfig.rst b/docs/narr/viewconfig.rst
index 2e0068e63..9b2074a70 100644
--- a/docs/narr/viewconfig.rst
+++ b/docs/narr/viewconfig.rst
@@ -63,14 +63,15 @@ View configuration is performed in one of these ways:
   :meth:`pyramid.config.Configurator.add_route` method, passing a ``view``
   argument specifying a view callable.
 
-- by using the :meth:`pyramid.config.Configurator.add_handler` against a
-  :term:`view handler` class (useful only for :term:`URL dispatch`
-  applications).
+.. note:: You can also add view configuration by adding a ``<view>`` or
+   ``<route>`` declaration to :term:`ZCML` used by your application as per
+   :ref:`mapping_views_using_zcml_section`, :ref:`view_directive` or
+   :ref:`route_directive`.
 
-.. note:: You can also add view configuration by adding a ``<view>``,
-   ``<route>`` or ``<handler>`` declaration to :term:`ZCML` used by your
-   application as per :ref:`mapping_views_using_zcml_section`,
-   :ref:`view_directive`, :ref:`route_directive` or :ref:`handler_directive`.
+.. note:: A package named ``pyramid_handlers`` (available from PyPI) provides
+   an analogue of :term:`Pylons` -style "controllers", which are a special
+   kind of view class which provides more automation when your application
+   uses :term:`URL dispatch` solely.
 
 .. _view_configuration_parameters:
 
@@ -599,7 +600,6 @@ which is the view itself or a :term:`dotted Python name` to such an object.
 All other arguments are optional.  See
 :meth:`pyramid.config.Configurator.add_view` for more information.
 
-
 .. index::
    single: resource interfaces
 
diff --git a/docs/narr/views.rst b/docs/narr/views.rst
index 4a54a6b16..3e0451383 100644
--- a/docs/narr/views.rst
+++ b/docs/narr/views.rst
@@ -130,8 +130,10 @@ method expected to return a response, you can either:
   values, each pointing at a different method of the class if you'd like the
   class to represent a collection of related view callables.
 
-- treat the class as a :term:`view handler` by using it as the ``handler=``
-  argument of a call to :meth:`pyramid.config.Configurator.add_handler`.
+.. note:: A package named ``pyramid_handlers`` (available from PyPI) provides
+   an analogue of :term:`Pylons` -style "controllers", which are a special
+   kind of view class which provides more automation when your application
+   uses :term:`URL dispatch` solely.
 
 .. note::
    You can also create :term:`view handler` classes that define