remove deprecated mechanism to associate views with routes; add description of scan mechanism

1 files changed, 34 insertions, 79 deletions

diff --git a/docs/narr/urldispatch.rst b/docs/narr/urldispatch.rst
index 51a840b8d..8e2d240fa 100644
--- a/docs/narr/urldispatch.rst
+++ b/docs/narr/urldispatch.rst
@@ -12,10 +12,10 @@ patterns is checked one-by-one.  If one of the patterns matches the path
 information associated with a request, a particular :term:`view
 callable` is invoked.  
 
-:term:`URL dispatch` is one of two ways to perform :term:`resource
-location` in :app:`Pyramid`; the other way is using :term:`traversal`.
-If no route is matched using :term:`URL dispatch`, :app:`Pyramid` falls
-back to :term:`traversal` to handle the :term:`request`.
+:term:`URL dispatch` is one of two ways to perform :term:`resource location`
+in :app:`Pyramid`; the other way is to use :term:`traversal`.  If no route is
+matched using :term:`URL dispatch`, :app:`Pyramid` falls back to
+:term:`traversal` to handle the :term:`request`.
 
 It is the responsibility of the :term:`resource location` subsystem
 (i.e., :term:`URL dispatch` or :term:`traversal`) to find the resource
@@ -67,8 +67,8 @@ attributes.
 
 .. _config-add-route:
 
-Configuring a Route via The ``add_route`` Configurator Method
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Configuring a Route to Match a View
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The :meth:`pyramid.config.Configurator.add_route` method adds a single
 :term:`route configuration` to the :term:`application registry`.  Here's an
@@ -84,90 +84,45 @@ example:
    config.add_route('myroute', '/prefix/{one}/{two}')
    config.add_view(myview, route_name='myroute')
 
-.. versionchanged:: 1.0a4
-    Prior to 1.0a4, routes allow for a marker starting with a ``:``, for
-    example ``/prefix/:one/:two``.  This style is now deprecated
-    in favor of ``{}`` usage which allows for additional functionality.
+When a :term:`view callable` added to the configuration by way of
+:meth:`~pyramid.config.Configurator.add_view` bcomes associated with a route
+via its ``route_name`` predicate, that view callable will always be found
+and invoked when the associated route pattern matches during a request.
 
-.. index::
-   single: route configuration; view callable
-
-.. _add_route_view_config:
-
-Route Configuration That Names a View Callable
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-.. warning:: This section describes a feature which has been deprecated in
-   Pyramid 1.1 and higher.  In order to reduce confusion and documentation
-   burden, passing view-related parameters to
-   :meth:`~pyramid.config.Configurator.add_route` is deprecated.
-
-   In versions earlier than 1.1, a view was permitted to be connected to a
-   route using a set of ``view*`` parameters passed to the
-   :meth:`~pyramid.config.Configurator.add_route`.  This was a shorthand
-   which replaced the need to perform a subsequent call to
-   :meth:`~pyramid.config.Configurator.add_view` as described in
-   :ref:`config-add-route`. For example, it was valid (and often recommended)
-   to do:
-
-   .. code-block:: python
+More commonly, you will not use any ``add_view`` statements in your project's
+"setup" code, instead only using ``add_route`` statements using a
+:term:`scan` for to associate view callables with routes.  For example, if
+this is a portion of your project's ``__init__.py``:
 
-      config.add_route('home', '/', view='mypackage.views.myview',
-                        view_renderer='some/renderer.pt')
-
-   Instead of the equivalent:
-
-   .. code-block:: python
-
-     config.add_route('home', '/')
-     config.add_view('mypackage.views.myview', route_name='home')
-                     renderer='some/renderer.pt')
-
-   Passing ``view*`` arguments to ``add_route`` as shown in the first
-   example above is now deprecated in favor of connecting a view to a
-   predefined route via :meth:`~pyramid.config.Configurator.add_view` using
-   the route's ``route_name`` parameter, as shown in the second example
-   above.
+.. code-block:: python
 
-   A deprecation warning is now issued when any view-related parameter is
-   passed to ``Configurator.add_route``.  The recommended way to associate a
-   view with a route is documented in :ref:`config-add-route`.
+   # in your project's __init__.py (mypackage.__init__)
 
-When a route configuration declaration names a ``view`` attribute, the value
-of the attribute will reference a :term:`view callable`.  This view callable
-will be invoked when the route matches.  A view callable, as described in
-:ref:`views_chapter`, is developer-supplied code that "does stuff" as the
-result of a request.
+   config.add_route('myroute', '/prefix/{one}/{two}')
+   config.scan('mypackage')
 
-Here's an example route configuration that references a view callable:
+Note that we don't call :meth:`~pyramid.config.Configurator.add_view` in this
+setup code.  However, the above :term:`scan` execution
+``config.scan('mypackage')`` will pick up all :term:`configuration
+decoration`, including any objects decorated with the
+:class:`pyramid.view.view_config` decorator in the ``mypackage`` Python
+pakage.  For example, if you have a ``views.py`` in your package, a scan will
+pick up any of its configuration decorators, so we can add one there that
+that references ``myroute`` as a ``route_name`` parameter:
 
 .. code-block:: python
-   :linenos:
-
-   # "config" below is presumed to be an instance of the
-   # pyramid.config.Configurator class; "myview" is assumed
-   # to be a "view callable" function
-   from myproject.views import myview
-   config.add_route('myroute', '/prefix/{one}/{two}', view=myview)
-
-You can also pass a :term:`dotted Python name` as the ``view`` argument
-rather than an actual callable:
 
-.. code-block:: python
-   :linenos:
+   # in your project's views.py module (mypackage.views)
 
-   # "config" below is presumed to be an instance of the
-   # pyramid.config.Configurator class; "myview" is assumed
-   # to be a "view callable" function
-   config.add_route('myroute', '/prefix/{one}/{two}', 
-                    view='myproject.views.myview')
+   from pyramid.view import view_config
+   from pyramid.response import Response
 
-When a route configuration names a ``view`` attribute, the :term:`view
-callable` named as that ``view`` attribute will always be found and invoked
-when the associated route pattern matches during a request.
+   @view_config(route_name='myroute')
+   def myview(request):
+       return Response('OK)
 
-See :meth:`pyramid.config.Configurator.add_route` for a description of
-view-related arguments.
+THe above combination of ``add_route`` and ``scan`` is completely equivalent
+to using the previous combination of ``add_route`` and ``add_view``.
 
 .. index::
    single: route path pattern syntax