8 files changed, 31 insertions, 11 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/project.rst b/docs/narr/project.rst
index fc1d473ac..b4397c09b 100644
--- a/docs/narr/project.rst
+++ b/docs/narr/project.rst
@@ -908,6 +908,17 @@ returns the HTML in a :term:`response`.
 See :ref:`views_which_use_a_renderer` for more information about how views,
 renderers, and templates relate and cooperate.
 
+.. note:: ``development.ini`` has a setting that controls how templates are
+   reloaded: ``pyramid.reload_templates``.
+    
+   - A setting of ``True`` (as in the scaffold ``development.ini``)
+     automatically reloads changed templates without a server restart.  This
+     is convenient while developing but slows template rendering speed.
+
+   - A setting of ``False`` (the default) requires a server restart to
+     integrate template changes.  Production applications should set
+     ``pyramid.reload_templates = False``.
+
 .. index::
    single: static directory
 
diff --git a/docs/narr/renderers.rst b/docs/narr/renderers.rst
index 4046c67fa..740c81555 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 don't.  Instead 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
 
diff --git a/docs/narr/upgrading.rst b/docs/narr/upgrading.rst
index ca6dc565b..64343ca3e 100644
--- a/docs/narr/upgrading.rst
+++ b/docs/narr/upgrading.rst
@@ -150,7 +150,7 @@ do things the newer way:
 .. code-block:: python
    :linenos:
 
-    from pyramid.view. import view_config
+    from pyramid.view import view_config
 
     from pyramid.static import static_view
     myview = static_view('static', 'static', use_subpath=True)
diff --git a/docs/tutorials/wiki2/src/authorization/tutorial/scripts/initializedb.py b/docs/tutorials/wiki2/src/authorization/tutorial/scripts/initializedb.py
index 092e359ce..23a5f13f4 100644
--- a/docs/tutorials/wiki2/src/authorization/tutorial/scripts/initializedb.py
+++ b/docs/tutorials/wiki2/src/authorization/tutorial/scripts/initializedb.py
@@ -33,5 +33,5 @@ def main(argv=sys.argv):
     DBSession.configure(bind=engine)
     Base.metadata.create_all(engine)
     with transaction.manager:
-        model = Page('FrontPage', 'This is the front page')
+        model = Page(name='FrontPage', data='This is the front page')
         DBSession.add(model)
diff --git a/docs/tutorials/wiki2/src/models/tutorial/scripts/initializedb.py b/docs/tutorials/wiki2/src/models/tutorial/scripts/initializedb.py
index 092e359ce..23a5f13f4 100644
--- a/docs/tutorials/wiki2/src/models/tutorial/scripts/initializedb.py
+++ b/docs/tutorials/wiki2/src/models/tutorial/scripts/initializedb.py
@@ -33,5 +33,5 @@ def main(argv=sys.argv):
     DBSession.configure(bind=engine)
     Base.metadata.create_all(engine)
     with transaction.manager:
-        model = Page('FrontPage', 'This is the front page')
+        model = Page(name='FrontPage', data='This is the front page')
         DBSession.add(model)
diff --git a/docs/tutorials/wiki2/src/tests/tutorial/scripts/initializedb.py b/docs/tutorials/wiki2/src/tests/tutorial/scripts/initializedb.py
index 092e359ce..23a5f13f4 100644
--- a/docs/tutorials/wiki2/src/tests/tutorial/scripts/initializedb.py
+++ b/docs/tutorials/wiki2/src/tests/tutorial/scripts/initializedb.py
@@ -33,5 +33,5 @@ def main(argv=sys.argv):
     DBSession.configure(bind=engine)
     Base.metadata.create_all(engine)
     with transaction.manager:
-        model = Page('FrontPage', 'This is the front page')
+        model = Page(name='FrontPage', data='This is the front page')
         DBSession.add(model)
diff --git a/docs/tutorials/wiki2/src/views/tutorial/scripts/initializedb.py b/docs/tutorials/wiki2/src/views/tutorial/scripts/initializedb.py
index 092e359ce..23a5f13f4 100644
--- a/docs/tutorials/wiki2/src/views/tutorial/scripts/initializedb.py
+++ b/docs/tutorials/wiki2/src/views/tutorial/scripts/initializedb.py
@@ -33,5 +33,5 @@ def main(argv=sys.argv):
     DBSession.configure(bind=engine)
     Base.metadata.create_all(engine)
     with transaction.manager:
-        model = Page('FrontPage', 'This is the front page')
+        model = Page(name='FrontPage', data='This is the front page')
         DBSession.add(model)