1 files changed, 50 insertions, 0 deletions
diff --git a/docs/narr/subrequest.rst b/docs/narr/subrequest.rst
index daa3cc43f..7c847de50 100644
--- a/docs/narr/subrequest.rst
+++ b/docs/narr/subrequest.rst
@@ -279,3 +279,53 @@ within a tween, because tweens already, by definition, have access to a
 function that will cause a subrequest (they are passed a ``handle`` function).
 It's fine to invoke :meth:`~pyramid.request.Request.invoke_subrequest` from
 within an event handler, however.
+
+
+.. index::
+   pair: subrequest; exception view
+
+Invoking an Exception View
+--------------------------
+
+.. versionadded:: 1.7
+
+:app:`Pyramid` apps may define :term:`exception views <exception view>` which
+can handle any raised exceptions that escape from your code while processing
+a request. By default an unhandled exception will be caught by the ``EXCVIEW``
+:term:`tween`, which will then lookup an exception view that can handle the
+exception type, generating an appropriate error response.
+
+In :app:`Pyramid` 1.7 the :meth:`pyramid.request.Request.invoke_exception_view`
+was introduced, allowing a user to invoke an exception view while manually
+handling an exception. This can be useful in a few different circumstances:
+
+- Manually handling an exception losing the current call stack or flow.
+
+- Handling exceptions outside of the context of the ``EXCVIEW`` tween. The
+  tween only covers certain parts of the request processing pipeline (See
+  :ref:`router_chapter`). There are also some corner cases where an exception
+  can be raised that will still bubble up to middleware, and possibly to the
+  web server in which case a generic ``500 Internal Server Error`` will be
+  returned to the client.
+
+Below is an example usage of
+:meth:`pyramid.request.Request.invoke_exception_view`:
+
+.. code-block:: python
+   :linenos:
+
+   def foo(request):
+       try:
+           some_func_that_errors()
+           return response
+       except Exception:
+           response = request.invoke_exception_view()
+           if response is not None:
+               return response
+           else:
+               # there is no exception view for this exception, simply
+               # re-raise and let someone else handle it
+               raise
+
+Please note that in most cases you do not need to write code like this, and you
+may rely on the ``EXCVIEW`` tween to handle this for you.