Docs: Link from renderer narrative docs to example render_to_response call, and index the example.

More fully explain the 2 examples, one with render_to_response call
and one without.

2 files changed, 15 insertions, 6 deletions

diff --git a/docs/narr/introduction.rst b/docs/narr/introduction.rst
index 032f4be6b..8c2acf95c 100644
--- a/docs/narr/introduction.rst
+++ b/docs/narr/introduction.rst
@@ -321,7 +321,14 @@ assertion instead that the view returns "the right stuff" in the dictionary
 it returns.  You can write "real" unit tests instead of functionally testing
 all of your views.
 
-For example, instead of:
+.. index::
+   pair: renderer; explicitly calling
+   pair: view renderer; explictly calling
+
+.. _example_render_to_response_call:
+
+For example, instead of returning a ``Response`` object from a
+``render_to_response`` call:
 
 .. code-block:: python
    :linenos:
@@ -332,7 +339,7 @@ For example, instead of:
         return render_to_response('myapp:templates/mytemplate.pt', {'a':1},
                                   request=request)
 
-You can do this:
+You can return a Python dictionary:
 
 .. code-block:: python
    :linenos:
diff --git a/docs/narr/renderers.rst b/docs/narr/renderers.rst
index 4046c67fa..b86f7298b 100644
--- a/docs/narr/renderers.rst
+++ b/docs/narr/renderers.rst
@@ -56,10 +56,12 @@ serialization techniques.  In practice, renderers obtain application data
 values from Python dictionaries so, in practice, view callables which use
 renderers return Python dictionaries.
 
-View configuration can vary the renderer associated with a view callable via
-the ``renderer`` attribute.  For example, this call to
-:meth:`~pyramid.config.Configurator.add_view` associates the ``json`` renderer
-with a view callable:
+View callables can :ref:`explicitly call
+<example_render_to_response_call>` renderers but, typically, view
+configuration declares the renderer used to render a view callable's
+results.  This is done with the ``renderer`` attribute.  For example,
+this call to :meth:`~pyramid.config.Configurator.add_view` associates
+the ``json`` renderer with a view callable:
 
 .. code-block:: python