1 files changed, 91 insertions, 19 deletions
diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst
index eaccc14a3..b7f052b00 100644
--- a/docs/narr/hooks.rst
+++ b/docs/narr/hooks.rst
@@ -19,24 +19,66 @@ found view`, which is a :term:`view callable`. A default notfound view
 exists.  The default not found view can be overridden through application
 configuration.
 
-The :term:`not found view` callable is a view callable like any other.  The
-:term:`view configuration` which causes it to be a "not found" view consists
-only of naming the :exc:`pyramid.httpexceptions.HTTPNotFound` class as the
-``context`` of the view configuration.
-
 If your application uses :term:`imperative configuration`, you can replace
-the Not Found view by using the :meth:`pyramid.config.Configurator.add_view`
-method to register an "exception view":
+the Not Found view by using the
+:meth:`pyramid.config.Configurator.add_notfound_view` method:
 
 .. code-block:: python
    :linenos:
 
-   from pyramid.httpexceptions import HTTPNotFound
-   from helloworld.views import notfound_view
-   config.add_view(notfound_view, context=HTTPNotFound)
+   from helloworld.views import notfound
+   config.add_notfound_view(notfound)
+
+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.
+
+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
+:class:`pyramid.view.notfound_view_config` decorator:
+
+.. code-block:: python
+   :linenos:
+
+   from pyramid.view import notfound_view_config
+
+   notfound_view_config()
+   def notfound(request):
+       return Response('Not Found, dude', status='404 Not Found')
+
+   def main(globals, **settings):
+      config = Configurator()
+      config.scan()
+
+This does exactly what the imperative example above showed.
+
+Your application can define *multiple* not found views if necessary.  Both
+:meth:`pyramid.config.Configurator.add_notfound_view` and
+:class:`pyramid.view.notfound_view_config` take most of the same arguments as
+:class:`pyramid.config.Configurator.add_view` and
+:class:`pyramid.view.view_config`, respectively.  This means that not found
+views can carry predicates limiting their applicability.  For example:
+
+.. code-block:: python
+   :linenos:
+
+   from pyramid.view import notfound_view_config
 
-Replace ``helloworld.views.notfound_view`` with a reference to the
-:term:`view callable` you want to use to represent the Not Found view.
+   notfound_view_config(request_method='GET')
+   def notfound_get(request):
+       return Response('Not Found during GET, dude', status='404 Not Found')
+
+   notfound_view_config(request_method='POST')
+   def notfound_post(request):
+       return Response('Not Found during POST, dude', status='404 Not Found')
+
+   def main(globals, **settings):
+      config = Configurator()
+      config.scan()
+
+The ``notfound_get`` view will be called when a view could not be found and
+the request method was ``GET``.  The ``notfound_post`` view will be called
+when a view could not be found and the request method was ``POST``.
 
 Like any other view, the notfound view must accept at least a ``request``
 parameter, or both ``context`` and ``request``.  The ``request`` is the
@@ -45,6 +87,11 @@ used in the call signature) will be the instance of the
 :exc:`~pyramid.httpexceptions.HTTPNotFound` exception that caused the view to
 be called.
 
+Both :meth:`pyramid.config.Configurator.add_notfound_view` and
+:class:`pyramid.view.notfound_view_config` can be used to automatically
+redirect requests to slash-appended routes. See
+:ref:`redirecting_to_slash_appended_routes` for examples.
+
 Here's some sample code that implements a minimal NotFound view callable:
 
 .. code-block:: python
@@ -52,7 +99,7 @@ Here's some sample code that implements a minimal NotFound view callable:
 
    from pyramid.httpexceptions import HTTPNotFound
 
-   def notfound_view(request):
+   def notfound(request):
        return HTTPNotFound()
 
 .. note::
@@ -66,6 +113,14 @@ Here's some sample code that implements a minimal NotFound view callable:
    ``pyramid.debug_notfound`` environment setting is true than it is when it
    is false.
 
+.. note::
+
+   Both :meth:`pyramid.config.Configurator.add_notfound_view` and
+   :class:`pyramid.view.notfound_view_config` are new as of Pyramid 1.3.
+   Older Pyramid documentation instructed users to use ``add_view`` instead,
+   with a ``context`` of ``HTTPNotFound``.  This still works; the convenience
+   method and decorator are just wrappers around this functionality.
+
 .. warning::
 
    When a NotFound view callable accepts an argument list as
@@ -90,23 +145,40 @@ the view which generates it can be overridden as necessary.
 
 The :term:`forbidden view` callable is a view callable like any other.  The
 :term:`view configuration` which causes it to be a "forbidden" view consists
-only of naming the :exc:`pyramid.httpexceptions.HTTPForbidden` class as the
-``context`` of the view configuration.
+of using the meth:`pyramid.config.Configurator.add_forbidden_view` API or the
+:class:`pyramid.view.forbidden_view_config` decorator.
 
-You can replace the forbidden view by using the
-:meth:`pyramid.config.Configurator.add_view` method to register an "exception
-view":
+For example, you can add a forbidden view by using the
+:meth:`pyramid.config.Configurator.add_forbidden_view` method to register a
+forbidden view:
 
 .. code-block:: python
    :linenos:
 
    from helloworld.views import forbidden_view
    from pyramid.httpexceptions import HTTPForbidden
-   config.add_view(forbidden_view, context=HTTPForbidden)
+   config.add_forbidden_view(forbidden_view)
 
 Replace ``helloworld.views.forbidden_view`` with a reference to the Python
 :term:`view callable` you want to use to represent the 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
+as a forbidden view:
+
+.. code-block:: python
+   :linenos:
+
+   from pyramid.view import forbidden_view_config
+
+   forbidden_view_config()
+   def forbidden(request):
+       return Response('forbidden')
+
+   def main(globals, **settings):
+      config = Configurator()
+      config.scan()
+
 Like any other view, the forbidden view must accept at least a ``request``
 parameter, or both ``context`` and ``request``.  The ``context`` (available
 as ``request.context`` if you're using the request-only view argument