From 35e632635b1b4e0a767024689d69d9469ae98c0f Mon Sep 17 00:00:00 2001
From: Michael Merickel <michael@merickel.org>
Date: Mon, 14 Mar 2016 23:28:15 -0500
Subject: add a docstring for add_view_deriver and expose the method to the api
 docs

---
 docs/api/config.rst     |  1 +
 docs/narr/hooks.rst     | 12 +++++++++---
 pyramid/config/views.py | 31 ++++++++++++++++++++++++++++++-
 3 files changed, 40 insertions(+), 4 deletions(-)

diff --git a/docs/api/config.rst b/docs/api/config.rst
index ae913d32c..e083dbc68 100644
--- a/docs/api/config.rst
+++ b/docs/api/config.rst
@@ -66,6 +66,7 @@
      .. automethod:: add_tween
      .. automethod:: add_route_predicate
      .. automethod:: add_view_predicate
+     .. automethod:: add_view_deriver
      .. automethod:: set_request_factory
      .. automethod:: set_root_factory
      .. automethod:: set_session_factory
diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst
index e3843cfbd..a5a03ef95 100644
--- a/docs/narr/hooks.rst
+++ b/docs/narr/hooks.rst
@@ -1580,6 +1580,10 @@ the user-defined :term:`view callable`:
   view pipeline interface to accept ``(context, request)`` from all previous
   view derivers.
 
+``rendered_view``
+
+  Adapts the result of :term:`view callable` into a :term:`response` object.
+
 ``decorated_view``
 
   Wraps the view with the decorators from the ``decorator`` option.
@@ -1615,8 +1619,10 @@ It is possible to define custom view derivers which will affect all views in
 an application. There are many uses for this but most will likely be centered
 around monitoring and security. In order to register a custom
 :term:`view deriver` you should create a callable that conforms to the
-:class:`pyramid.interfaces.IViewDeriver` interface. For example, below
-is a callable that can provide timing information for the view pipeline:
+:class:`pyramid.interfaces.IViewDeriver` interface and then register it with
+your application using :meth:`pyramid.config.Configurator.add_view_deriver`.
+For example, below is a callable that can provide timing information for the
+view pipeline:
 
 .. code-block:: python
    :linenos:
@@ -1676,7 +1682,7 @@ Ordering View Derivers
 ~~~~~~~~~~~~~~~~~~~~~~
 
 By default, every new view deriver is added between the ``decorated_view``
-and ``mapped_view`` built-in derivers. It is possible to customize this
+and ``rendered_view`` built-in derivers. It is possible to customize this
 ordering using the ``over`` and ``under`` options. Each option can use the
 names of other view derivers in order to specify an ordering. There should
 rarely be a reason to worry about the ordering of the derivers.
diff --git a/pyramid/config/views.py b/pyramid/config/views.py
index 6f8b24aa2..e90b95420 100644
--- a/pyramid/config/views.py
+++ b/pyramid/config/views.py
@@ -1091,7 +1091,36 @@ class ViewsConfiguratorMixin(object):
             self.add_view_predicate(name, factory)
 
     @action_method
-    def add_view_deriver(self, deriver, name=None, under=None, over=None):
+    def add_view_deriver(self, deriver, name, under=None, over=None):
+        """
+        .. versionadded:: 1.7
+
+        Add a :term:`view deriver` to the view pipeline. View derivers are
+        a feature used by extension authors to wrap views in custom code
+        controllable by view-specific options.
+
+        ``deriver`` should be a callable conforming to the
+        :class:`pyramid.interfaces.IViewDeriver` interface.
+
+        ``name`` should be the name of the view deriver.  There are no
+        restrictions on the name of a view deriver. If left unspecified, the
+        name will be constructed from the name of the ``deriver``.
+
+        The ``under`` and ``over`` options may be used to control the ordering
+        of view derivers by providing hints about where in the view pipeline
+        the deriver is used.
+
+        ``under`` means further away from user-defined :term:`view callable`,
+        and ``over`` means closer to the original :term:`view callable`.
+
+        Specifying neither ``under`` nor ``over`` is equivalent to specifying
+        ``over='decorated_view'`` and ``under='rendered_view'``, placing the
+        deriver somewhere between the ``decorated_view`` and ``rendered_view``
+        derivers.
+
+        See :ref:`view_derivers` for more information.
+
+        """
         deriver = self.maybe_dotted(deriver)
 
         if under is None and over is None:
-- 
cgit v1.2.3