- Make sure deprecation warnings aren't raised when tests are run.

- Modify documentation for cross-referencing.

- Use add_view(viewname) syntax rather than add_view(view=viewname)
  syntax for normalization.

- Use warnings.warn rather than zope.deprecated in order to make
  testing easier.

- Move tests which test deprecated methods of configurator to a
  separate test case.

4 files changed, 87 insertions, 85 deletions

diff --git a/docs/narr/advconfig.rst b/docs/narr/advconfig.rst
index 7ae80155b..5ee554284 100644
--- a/docs/narr/advconfig.rst
+++ b/docs/narr/advconfig.rst
@@ -295,15 +295,9 @@ These are the methods of the configurator which provide conflict detection:
 :meth:`~pyramid.config.Configurator.set_locale_negotiator` and
 :meth:`~pyramid.config.Configurator.set_default_permission`.
 
-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_route` does a second type of
-  conflict detection when a ``view`` parameter is passed (it calls
-  ``add_view``). This behavior has been deprecated in :app:`Pyramid` 1.1.
-
-- :meth:`~pyramid.config.Configurator.static_view`, a frontend for
-  ``add_route`` and ``add_view``.
+:meth:`~pyramid.config.Configurator.add_static_view` also indirectly
+provides conflict detection, because it's implemented in terms of the
+conflict-aware ``add_route`` and ``add_view`` methods.
 
 .. _including_configuration:
 
diff --git a/docs/narr/hybrid.rst b/docs/narr/hybrid.rst
index d66ad59df..f8ed743fb 100644
--- a/docs/narr/hybrid.rst
+++ b/docs/narr/hybrid.rst
@@ -33,7 +33,7 @@ URL Dispatch Only
 ~~~~~~~~~~~~~~~~~
 
 An application that uses :term:`url dispatch` exclusively to map URLs to code
-will often have statements like this within your application startup
+will often have statements like this within application startup
 configuration:
 
 .. code-block:: python
@@ -47,9 +47,14 @@ configuration:
    config.add_view('myproject.views.foobar', route_name='foobar')
    config.add_view('myproject.views.bazbuz', route_name='bazbuz')
 
-Each :term:`route` corresponds to one or more view callables,
-and when that route is matched during a request, :term:`view lookup` is used
-to match the request to one of the view callables.
+Each :term:`route` corresponds to one or more view callables.  Each view
+callable is associated with a route by passing a ``route_name`` parameter
+that matches its name during a call to
+:meth:`~pyramid.config.Configurator.add_view`.  When a route is matched
+during a request, :term:`view lookup` is used to match the request to its
+associated view callable.  The presence of calls to
+:meth:`~pyramid.config.Configurator.add_route` signify that an application is
+using URL dispatch.
 
 Traversal Only
 ~~~~~~~~~~~~~~
@@ -423,13 +428,11 @@ attribute.
 Using ``*subpath`` in a Route Pattern
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-There are certain extremely rare cases when you'd like to influence
-the traversal :term:`subpath` when a route matches without actually
-performing traversal.  For instance, the
-:func:`pyramid.wsgi.wsgiapp2` decorator and the
-:class:`pyramid.view.static` helper attempt to compute
-``PATH_INFO`` from the request's subpath, so it's useful to be able to
-influence this value.
+There are certain extremely rare cases when you'd like to influence the
+traversal :term:`subpath` when a route matches without actually performing
+traversal.  For instance, the :func:`pyramid.wsgi.wsgiapp2` decorator and the
+:class:`pyramid.view.static` helper attempt to compute ``PATH_INFO`` from the
+request's subpath, so it's useful to be able to influence this value.
 
 When ``*subpath`` exists in a pattern, no path is actually traversed,
 but the traversal algorithm will return a :term:`subpath` list implied
@@ -455,14 +458,16 @@ application.  We'll detail them here.
 Registering a Default View for a Route That Has a ``view`` Attribute
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. note:: As of :app:`Pyramid` 1.1 this issue is deprecated along with
-    the ability to add views directly to the :term:`route configuration`.
+.. warning:: As of :app:`Pyramid` 1.1 this section is slated to be removed in
+   a later documentation release because the the ability to add views
+   directly to the :term:`route configuration` by passing a ``view`` argument
+   to ``add_route`` has been deprecated.
 
 It is an error to provide *both* a ``view`` argument to a :term:`route
 configuration` *and* a :term:`view configuration` which names a
 ``route_name`` that has no ``name`` value or the empty ``name`` value.  For
-example, this pair of declarations will generate a "conflict" error at
-startup time.
+example, this pair of declarations will generate a conflict error at startup
+time.
 
 .. code-block:: python
    :linenos:
@@ -490,8 +495,8 @@ Can also be spelled like so:
    config.add_route('home', '{foo}/{bar}/*traverse')
    config.add_view('myproject.views.home', route_name='home')
 
-The two spellings are logically equivalent.  In fact, the former is
-just a syntactical shortcut for the latter.
+The two spellings are logically equivalent.  In fact, the former is just a
+syntactical shortcut for the latter.
 
 Binding Extra Views Against a Route Configuration that Doesn't Have a ``*traverse`` Element In Its Pattern
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/docs/narr/urldispatch.rst b/docs/narr/urldispatch.rst
index 2a8052861..4923fd19f 100644
--- a/docs/narr/urldispatch.rst
+++ b/docs/narr/urldispatch.rst
@@ -54,13 +54,13 @@ Route Configuration
 -------------------
 
 :term:`Route configuration` is the act of adding a new :term:`route` to an
-application.  A route has a *pattern*, representing a pattern meant to match
+application.  A route has a *name*, which acts as an identifier to be used
+for URL generation.  The name also allows developers to associate a view
+configuration with the route.  A route also has a *pattern*, meant to match
 against the ``PATH_INFO`` portion of a URL (the portion following the scheme
-and port, e.g. ``/foo/bar`` in the URL ``http://localhost:8080/foo/bar``),
-and a *route name*, which is used by developers within a :app:`Pyramid`
-application to uniquely identify a particular route when generating a URL.
-It also optionally has a ``factory``, a set of :term:`route predicate`
-parameters, and a set of view callables.
+and port, e.g. ``/foo/bar`` in the URL ``http://localhost:8080/foo/bar``). It
+also optionally has a ``factory`` and a set of :term:`route predicate`
+attributes.
 
 .. index::
    single: add_route
@@ -89,22 +89,49 @@ example:
     example ``/prefix/:one/:two``.  This style is now deprecated
     in favor of ``{}`` usage which allows for additional functionality.
 
-.. versionchanged:: 1.1
-    Prior to 1.1, views were typically connected to routes using a set of
-    view parameters on :meth:`pyramid.config.Configurator.add_route`. That
-    behavior is now deprecated in favor of connecting views to routes using
-    :meth:`pyramid.config.Configurator.add_view` with the ``route_name``
-    parameter.
-
 .. 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. The recommended way to connect view callables to routes
-    is via :ref:`config-add-route`.
+   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
+
+      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.
+
+   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`.
 
 When a route configuration declaration names a ``view`` attribute, the value
 of the attribute will reference a :term:`view callable`.  This view callable
@@ -139,6 +166,9 @@ 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.
 
+See :ref:`add_route_view_related_api` for a description of view-related
+arguments to ``add_route``.
+
 .. index::
    single: route path pattern syntax
 
@@ -377,7 +407,8 @@ resource of the view callable ultimately found via :term:`view lookup`.
 .. code-block:: python
    :linenos:
 
-   config.add_route('abc', '/abc', factory='myproject.resources.root_factory')
+   config.add_route('abc', '/abc', 
+                    factory='myproject.resources.root_factory')
    config.add_view('myproject.views.theview', route_name='abc')
 
 The factory can either be a Python object or a :term:`dotted Python name` (a
@@ -410,7 +441,7 @@ process.  Examples of route predicate arguments are ``pattern``, ``xhr``, and
 
 Other arguments are view configuration related arguments.  These only have an
 effect when the route configuration names a ``view``. These arguments have
-been deprecated as of :app:`Pyramid` 1.1.
+been deprecated as of :app:`Pyramid` 1.1 (see :ref:`add_route_view_config`).
 
 Other arguments are ``name`` and ``factory``.  These arguments represent
 neither predicates nor view configuration information.
@@ -562,8 +593,8 @@ If any route matches, the route matching process stops.  The :term:`request`
 is decorated with a special :term:`interface` which describes it as a "route
 request", the :term:`context` resource is generated, and the context and the
 resulting request are handed off to :term:`view lookup`.  During view lookup,
-if any ``view`` was provided within the matched route configuration, the
-:term:`view callable` it points to is called.
+if a :term:`view callable` associated with the matched route is found, that
+view is called.
 
 When a route configuration is declared, it may contain :term:`route
 predicate` arguments.  All route predicates associated with a route
@@ -754,34 +785,6 @@ request in its ``__init__``.  For example:
 In a more complicated application, this root factory might be a class
 representing a :term:`SQLAlchemy` model.
 
-Example 4
-~~~~~~~~~
-
-It is possible to create a route declaration without a ``view`` attribute,
-but associate the route with a :term:`view callable` using a ``view``
-declaration.
-
-.. code-block:: python
-   :linenos:
-
-   config.add_route('idea', 'site/{id}')
-   config.add_view(route_name='idea', view='mypackage.views.site_view')
-
-This set of configuration parameters creates a configuration completely
-equivalent to this example provided in :ref:`urldispatch_example1`:
-
-.. code-block:: python
-   :linenos:
-
-   config.add_route('idea', 'site/{id}', view='mypackage.views.site_view')
-
-In fact, the spelling which names a ``view`` attribute is just syntactic
-sugar for the more verbose spelling which contains separate view and route
-registrations.
-
-More uses for this style of associating views with routes are explored in
-:ref:`hybrid_chapter`.
-
 .. index::
    single: matching the root URL
    single: root url (matching)
@@ -884,8 +887,8 @@ the application's startup configuration, adding the following stanza:
 .. code-block:: python
    :linenos:
 
-   config.add_view(context='pyramid.exceptions.NotFound',
-                   view='pyramid.view.append_slash_notfound_view')
+   config.add_view('pyramid.view.append_slash_notfound_view', 
+                   context='pyramid.exceptions.NotFound')
 
 See :ref:`view_module` and :ref:`changing_the_notfound_view` for more
 information about the slash-appending not found view and for a more general
@@ -1083,25 +1086,25 @@ is executed.
 Route View Callable Registration and Lookup Details
 ---------------------------------------------------
 
-When a request enters the system which matches the pattern of the route,
-the result is simple: the view callable associated with the route is invoked
-with the request that caused the invocation.
+When a request enters the system which matches the pattern of the route, the
+usual result is simple: the view callable associated with the route is
+invoked with the request that caused the invocation.
 
 For most usage, you needn't understand more than this; how it works is an
 implementation detail.  In the interest of completeness, however, we'll
 explain how it *does* work in the this section.  You can skip it if you're
 uninterested.
 
-When a ``view`` is attached to a route configuration, :app:`Pyramid` ensures
-that a :term:`view configuration` is registered that will always be found when
-the route pattern is matched during a request.  To do so:
+When a view is associated with a route configuration, :app:`Pyramid` ensures
+that a :term:`view configuration` is registered that will always be found
+when the route pattern is matched during a request.  To do so:
 
 - A special route-specific :term:`interface` is created at startup time for
   each route configuration declaration.
 
-- When a route configuration declaration mentions a ``view`` attribute, a
+- When an ``add_view`` statement mentions a ``route name`` attribute, a
   :term:`view configuration` is registered at startup time.  This view
-  configuration uses the route-specific interface as a :term:`request` type.
+  configuration uses a route-specific interface as a :term:`request` type.
 
 - At runtime, when a request causes any route to match, the :term:`request`
   object is decorated with the route-specific interface.
diff --git a/docs/narr/viewconfig.rst b/docs/narr/viewconfig.rst
index 7ee8e3fe5..743cc016e 100644
--- a/docs/narr/viewconfig.rst
+++ b/docs/narr/viewconfig.rst
@@ -59,8 +59,8 @@ View configuration is performed in one of these ways:
 - By specifying a view within a :term:`route configuration`.  View
   configuration via a route configuration is performed by using the
   :meth:`pyramid.config.Configurator.add_route` method, passing a ``view``
-  argument specifying a view callable. This method is deprecated as of
-  :app:`Pyramid` 1.1.
+  argument specifying a view callable. This pattern of view configuration is
+  deprecated as of :app:`Pyramid` 1.1.
 
 .. note:: A package named ``pyramid_handlers`` (available from PyPI) provides
    an analogue of :term:`Pylons` -style "controllers", which are a special