14 files changed, 68 insertions, 60 deletions
diff --git a/docs/narr/advconfig.rst b/docs/narr/advconfig.rst
index 434e2bd6c..1b8e33de3 100644
--- a/docs/narr/advconfig.rst
+++ b/docs/narr/advconfig.rst
@@ -148,14 +148,14 @@ one:
        config.add_route(...)
 
 Don't call this function directly with ``config`` as an argument.  Instead,
-use :meth:`pyramid.config.Configuration.include`:
+use :meth:`pyramid.config.Configurator.include`:
 
 .. code-block:: python
    :linenos:
 
    config.include(add_routes)
 
-Using :meth:`~pyramid.config.Configuration.include` instead of calling the
+Using :meth:`~pyramid.config.Configurator.include` instead of calling the
 function directly provides a modicum of automated conflict resolution, with
 the configuration statements you define in the calling code overriding those
 of the included function.  See also :ref:`automatic_conflict_resolution` and
@@ -333,7 +333,7 @@ his application:
        config.add_route(...)
 
 Rather than calling this function directly with ``config`` as an argument.
-Instead, use :meth:`pyramid.config.Configuration.include`:
+Instead, use :meth:`pyramid.config.Configurator.include`:
 
 .. code-block:: python
    :linenos:
@@ -343,7 +343,7 @@ 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`
+:meth:`~pyramid.config.Configurator.include` can also accept a :term:`module`
 as an argument:
 
 .. code-block:: python
@@ -357,7 +357,7 @@ 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
+:meth:`~pyramid.config.Configurator.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
diff --git a/docs/narr/assets.rst b/docs/narr/assets.rst
index 09a2b83f2..26b3e3a92 100644
--- a/docs/narr/assets.rst
+++ b/docs/narr/assets.rst
@@ -271,7 +271,7 @@ assets which begin with ``mypackage:images`` will be prefixed with
    # -> http://example.com/images/logo.png
 
 Using :meth:`~pyramid.request.Request.static_url` in conjunction with a
-:meth:`~pyramid.configuration.Configurator.add_static_view` makes it possible
+:meth:`~pyramid.config.Configurator.add_static_view` makes it possible
 to put static media on a separate webserver during production (if the
 ``name`` argument to :meth:`~pyramid.config.Configurator.add_static_view` is
 a URL), while keeping static media package-internal and served by the
diff --git a/docs/narr/environment.rst b/docs/narr/environment.rst
index e059acc4e..f0c0c18fe 100644
--- a/docs/narr/environment.rst
+++ b/docs/narr/environment.rst
@@ -302,7 +302,7 @@ Ideally, you won't need to use the ``pyramid.tweens`` setting at all.  Tweens
 are generally ordered and included "implicitly" when an add-on package which
 registers a tween is "included".  Packages are included when you name a
 ``pyramid.includes`` setting in your configuration or when you call
-:meth:`pyramid.config.Configuration.include`.
+:meth:`pyramid.config.Configurator.include`.
 
 Authors of included add-ons provide "implicit" tween configuration ordering
 hints to Pyramid when their packages are included.  However, the implicit
diff --git a/docs/narr/extconfig.rst b/docs/narr/extconfig.rst
index f33326279..659056952 100644
--- a/docs/narr/extconfig.rst
+++ b/docs/narr/extconfig.rst
@@ -129,8 +129,8 @@ called (either explicitly or as the result of calling
 :meth:`~pyramid.config.Configurator.make_wsgi_app`), conflicting actions are
 potentially automatically resolved as per
 :ref:`automatic_conflict_resolution`.  If a conflict cannot be automatically
-resolved, a :exc:`ConfigurationConflictError` is raised and application
-startup is prevented.
+resolved, a :exc:`pyramid.exceptions.ConfigurationConflictError` is raised
+and application startup is prevented.
 
 In our above example, therefore, if a consumer of our ``add_jammyjam``
 directive did this:
diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst
index a3de23baa..37a74b53a 100644
--- a/docs/narr/hooks.rst
+++ b/docs/narr/hooks.rst
@@ -14,8 +14,8 @@ in various ways.
 Changing the Not Found View
 ---------------------------
 
-When :app:`Pyramid` can't map a URL to view code, it invokes a :term:`not
-found view`, which is a :term:`view callable`. The default Not Found View
+When :app:`Pyramid` can't map a URL to view code, it invokes a :term:`Not
+Found View`, which is a :term:`view callable`. The default Not Found View
 can be overridden through application configuration.
 
 If your application uses :term:`imperative configuration`, you can replace
@@ -25,15 +25,17 @@ the Not Found View by using the
 .. code-block:: python
    :linenos:
 
-   from helloworld.views import notfound
-   config.add_notfound_view(notfound)
+   def notfound(request):
+       return Response('Not Found, dude', status='404 Not Found')
 
-Replace ``helloworld.views.notfound`` with a reference to the :term:`view
-callable` you want to use to represent the Not Found View.  The :term:`not
-found view` callable is a view callable like any other.
+   def main(globals, **settings):
+       config = Configurator()
+       config.add_notfound_view(notfound)
+
+The :term:`Not Found View` callable is a view callable like any other.
 
 If your application instead uses :class:`pyramid.view.view_config` decorators
-and a :term:`scan`, you can replace the Not Found view by using the
+and a :term:`scan`, you can replace the Not Found View by using the
 :class:`pyramid.view.notfound_view_config` decorator:
 
 .. code-block:: python
@@ -46,8 +48,8 @@ and a :term:`scan`, you can replace the Not Found view by using the
        return Response('Not Found, dude', status='404 Not Found')
 
    def main(globals, **settings):
-      config = Configurator()
-      config.scan()
+       config = Configurator()
+       config.scan()
 
 This does exactly what the imperative example above showed.
 
@@ -154,12 +156,12 @@ forbidden view:
 .. code-block:: python
    :linenos:
 
-   from helloworld.views import forbidden_view
-   from pyramid.httpexceptions import HTTPForbidden
-   config.add_forbidden_view(forbidden_view)
+   def forbidden(request):
+       return Response('forbidden')
 
-Replace ``helloworld.views.forbidden_view`` with a reference to the Python
-:term:`view callable` you want to use to represent the Forbidden view.
+   def main(globals, **settings):
+       config = Configurator()
+       config.add_forbidden_view(forbidden_view)
 
 If instead you prefer to use decorators and a :term:`scan`, you can use the
 :class:`pyramid.view.forbidden_view_config` decorator to mark a view callable
@@ -673,7 +675,7 @@ traverser.
 If you've added a traverser, you can change how
 :meth:`~pyramid.request.Request.resource_url` generates a URL for a specific
 type of resource by adding a call to
-:meth:`pyramid.config.add_resource_url_adapter`.
+:meth:`pyramid.config.Configurator.add_resource_url_adapter`.
 
 For example:
 
@@ -929,7 +931,7 @@ set a *default* view mapper (overriding the superdefault view mapper used by
 Pyramid itself).
 
 A *single* view registration can use a view mapper by passing the mapper as
-the ``mapper`` argument to :meth:`~pyramid.config.Configuration.add_view`.
+the ``mapper`` argument to :meth:`~pyramid.config.Configurator.add_view`.
 
 .. index::
    single: configuration decorator
diff --git a/docs/narr/renderers.rst b/docs/narr/renderers.rst
index b4eb95186..20a9eda31 100644
--- a/docs/narr/renderers.rst
+++ b/docs/narr/renderers.rst
@@ -33,14 +33,11 @@ by the view must be compatible with the particular kind of renderer used, or
 an error may occur during view invocation.
 
 One exception exists: it is *always* OK to return a Response object, even
-when a ``renderer`` is configured.  If a view callable returns a response
-object from a view that is configured with a renderer, the renderer is
+when a ``renderer`` is configured.  In such cases, the renderer is
 bypassed entirely.
 
 Various types of renderers exist, including serialization renderers
-and renderers which use templating systems.  See also
-:ref:`views_which_use_a_renderer`.
-
+and renderers which use templating systems.
 
 .. index::
    single: renderer
@@ -51,8 +48,8 @@ and renderers which use templating systems.  See also
 Writing View Callables Which Use a Renderer
 -------------------------------------------
 
-As we've seen, view callables needn't always return a Response object.
-Instead, they may return an arbitrary Python object, with the expectation
+As we've seen, a view callable needn't always return a Response object.
+Instead, it may return an arbitrary Python object, with the expectation
 that a :term:`renderer` will convert that object into a response instance on
 your behalf.  Some renderers use a templating system; other renderers use
 object serialization techniques.
@@ -80,12 +77,10 @@ response attributes (such as headers and the HTTP status code) by attaching a
 property to the ``request.response`` attribute.
 See :ref:`request_response_attr`.
 
-If the :term:`view callable` associated with a :term:`view configuration`
-returns a Response object directly, any renderer associated with the view
-configuration is ignored, and the response is passed back to :app:`Pyramid`
-unchanged.  For example, if your view callable returns an instance of the
-:class:`pyramid.response.Response` class as a response, no renderer
-will be employed.
+As already mentioned, if the :term:`view callable` associated with a
+:term:`view configuration` returns a Response object (or its instance),
+any renderer associated with the view configuration is ignored,
+and the response is passed back to :app:`Pyramid` unchanged.  For example:
 
 .. code-block:: python
    :linenos:
@@ -140,7 +135,7 @@ used in the ``renderer`` attribute of view configurations.
 ``string``: String Renderer
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The ``string`` renderer is a renderer which renders a view callable result to
+The ``string`` renderer renders a view callable result to
 a string.  If a view callable returns a non-Response object, and the
 ``string`` renderer is associated in that view's configuration, the result
 will be to run the object through the Python ``str`` function to generate a
diff --git a/docs/narr/resources.rst b/docs/narr/resources.rst
index a24c44f29..699a3d4ac 100644
--- a/docs/narr/resources.rst
+++ b/docs/narr/resources.rst
@@ -171,7 +171,7 @@ you will reach the filesystem root directory.
    URL generated (as opposed to a single leading slash or empty tuple
    element).
 
-.. sidebar::  Using :mod:`pyramid_traversalwrapper`
+.. sidebar:: For your convenience
 
   If you'd rather not manage the ``__name__`` and ``__parent__`` attributes
   of your resources "by hand", an add-on package named
diff --git a/docs/narr/scaffolding.rst b/docs/narr/scaffolding.rst
index 9ac579a87..534b2caf4 100644
--- a/docs/narr/scaffolding.rst
+++ b/docs/narr/scaffolding.rst
@@ -74,10 +74,14 @@ concrete examples of scaffold directories (``zodb``, ``alchemy``, and
 After you've created the template directory, add the following to the
 ``entry_points`` value of your distribution's ``setup.py``:
 
-      [pyramid.scaffold]
-      coolextension=coolextension.scaffolds:CoolExtensionTemplate
+.. code-block:: ini
+
+   [pyramid.scaffold]
+   coolextension=coolextension.scaffolds:CoolExtensionTemplate
 
-For example::
+For example:
+
+.. code-block:: python
 
     def setup(
           ...,
@@ -95,7 +99,7 @@ because that's the name we gave it in the entry point setup.  Running
 output directory named ``MyStuff``.
 
 See the module documentation for :mod:`pyramid.scaffolds` for information
-about the API of the :class:`pyramid.scaffolds.PyramidScaffold` class and
+about the API of the :class:`pyramid.scaffolds.Template` class and
 related classes.  You can override methods of this class to get special
 behavior.
 
diff --git a/docs/narr/security.rst b/docs/narr/security.rst
index e91e8c542..6517fedf8 100644
--- a/docs/narr/security.rst
+++ b/docs/narr/security.rst
@@ -331,7 +331,7 @@ A principal is usually a user id, however it also may be a group id if your
 authentication system provides group information and the effective
 :term:`authentication policy` policy is written to respect group information.
 For example, the
-:class:`pyramid.authentication.RepozeWho1AuthenicationPolicy` respects group
+:class:`pyramid.authentication.RepozeWho1AuthenticationPolicy` respects group
 information if you configure it with a ``callback``.
 
 Each ACE in an ACL is processed by an authorization policy *in the
diff --git a/docs/narr/subrequest.rst b/docs/narr/subrequest.rst
index 93ce747ee..6437bd0fa 100644
--- a/docs/narr/subrequest.rst
+++ b/docs/narr/subrequest.rst
@@ -223,16 +223,16 @@ unconditionally:
   :meth:`~pyramid.config.Configurator.set_request_property`) on the subrequest
   object passed as ``request``
 
-- causes a :class:`~pyramid.event.NewRequest` event to be sent at the
+- causes a :class:`~pyramid.events.NewRequest` event to be sent at the
   beginning of request processing.
 
-- causes a :class:`~pyramid.event.ContextFound` event to be sent when a
+- causes a :class:`~pyramid.events.ContextFound` event to be sent when a
   context resource is found.
-  
+
 - Ensures that the user implied by the request passed has the necessary
   authorization to invoke view callable before calling it.
 
-- causes a :class:`~pyramid.event.NewResponse` event to be sent when the
+- causes a :class:`~pyramid.events.NewResponse` event to be sent when the
   Pyramid application returns a response.
 
 - Calls any :term:`response callback` functions defined within the subrequest's
diff --git a/docs/narr/testing.rst b/docs/narr/testing.rst
index bfb1287d9..88d6904c7 100644
--- a/docs/narr/testing.rst
+++ b/docs/narr/testing.rst
@@ -125,7 +125,7 @@ method attached to ``MyTest`` will use an isolated registry.
 
 The :func:`~pyramid.testing.setUp` and :func:`~pyramid.testing.tearDown`
 functions accepts various arguments that influence the environment of the
-test.  See the :ref:`testing_module` chapter for information about the extra
+test.  See the :ref:`testing_module` API for information about the extra
 arguments supported by these functions.
 
 If you also want to make :func:`~pyramid.threadlocal.get_current_request` return something
@@ -202,7 +202,7 @@ any ``get_current*`` function.
 Using the ``Configurator`` and ``pyramid.testing`` APIs in Unit Tests
 ---------------------------------------------------------------------
 
-The ``Configurator`` API and the ``pyramid.testing`` module provide a number
+The ``Configurator`` API and the :mod:`pyramid.testing` module provide a number
 of functions which can be used during unit testing.  These functions make
 :term:`configuration declaration` calls to the current :term:`application
 registry`, but typically register a "stub" or "dummy" feature in place of the
@@ -222,6 +222,12 @@ function.
            raise HTTPForbidden
        return {'greeting':'hello'}
 
+.. note::
+
+   This code implies that you have defined a renderer imperatively in a
+   relevant :class:`pyramid.config.Configurator` instance,
+   otherwise it would fail when run normally.
+
 Without doing anything special during a unit test, the call to
 :func:`~pyramid.security.has_permission` in this view function will always
 return a ``True`` value.  When a :app:`Pyramid` application starts normally,
@@ -291,7 +297,7 @@ function is called, :func:`pyramid.security.has_permission` will call the
 access.  We check that the view function raises a
 :exc:`~pyramid.httpexceptions.HTTPForbidden` error.
 
-The second test method, named ``test_view_fn_allowed`` tests the alternate
+The second test method, named ``test_view_fn_allowed``, tests the alternate
 case, where the authentication policy allows access.  Notice that we pass
 different values to
 :meth:`~pyramid.config.Configurator.testing_securitypolicy` to obtain this
@@ -373,7 +379,7 @@ after accessing some values that require a fully set up environment.
            result = my_view(request)
            self.assertEqual(result.status, '200 OK')
            body = result.app_iter[0]
-           self.failUnless('Welcome to' in body)
+           self.assertTrue('Welcome to' in body)
            self.assertEqual(len(result.headerlist), 2)
            self.assertEqual(result.headerlist[0],
                             ('Content-Type', 'text/html; charset=UTF-8'))
@@ -416,7 +422,7 @@ functional testing package written by Ian Bicking.
 
        def test_root(self):
            res = self.testapp.get('/', status=200)
-           self.failUnless('Pyramid' in res.body)
+           self.assertTrue('Pyramid' in res.body)
 
 When this test is run, each test creates a "real" WSGI application using the
 ``main`` function in your ``myapp.__init__`` module and uses :term:`WebTest`
diff --git a/docs/narr/threadlocals.rst b/docs/narr/threadlocals.rst
index 5ff70565c..a90ee4905 100644
--- a/docs/narr/threadlocals.rst
+++ b/docs/narr/threadlocals.rst
@@ -129,7 +129,7 @@ follows:
   ever be called within application-specific forks of third-party
   library code.  The library you've forked almost certainly has
   nothing to do with :app:`Pyramid`, and making it dependent on
-  :app:`Pyramid` (rather than making your :mod:`pyramid`
+  :app:`Pyramid` (rather than making your :app:`pyramid`
   application depend upon it) means you're forming a dependency in the
   wrong direction.
 
diff --git a/docs/narr/viewconfig.rst b/docs/narr/viewconfig.rst
index 6f0001f61..241ce62b5 100644
--- a/docs/narr/viewconfig.rst
+++ b/docs/narr/viewconfig.rst
@@ -908,10 +908,11 @@ per :ref:`protecting_views`.
 
 .. _debug_notfound_section:
 
-:exc:`NotFound` Errors
-~~~~~~~~~~~~~~~~~~~~~~
+:exc:`~pyramid.exceptions.NotFound` Errors
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-It's useful to be able to debug :exc:`NotFound` error responses when they
+It's useful to be able to debug :exc:`~pyramid.exceptions.NotFound`
+error responses when they
 occur unexpectedly due to an application registry misconfiguration.  To debug
 these errors, use the ``PYRAMID_DEBUG_NOTFOUND`` environment variable or the
 ``pyramid.debug_notfound`` configuration file setting.  Details of why a view
diff --git a/docs/narr/webob.rst b/docs/narr/webob.rst
index 02c03c8db..c0ca450b1 100644
--- a/docs/narr/webob.rst
+++ b/docs/narr/webob.rst
@@ -487,7 +487,7 @@ module.
 Each class is named ``pyramid.httpexceptions.HTTP*``, where ``*`` is the
 reason for the error.  For instance,
 :class:`pyramid.httpexceptions.HTTPNotFound` subclasses
-:class:`pyramid.Response`, so you can manipulate the instances in the same
+:class:`pyramid.response.Response`, so you can manipulate the instances in the same
 way.  A typical example is:
 
 .. code-block:: python