Merge branch 'master' of github.com:Pylons/pyramid

4 files changed, 61 insertions, 36 deletions

diff --git a/docs/narr/introduction.rst b/docs/narr/introduction.rst
index 032f4be6b..ece720a97 100644
--- a/docs/narr/introduction.rst
+++ b/docs/narr/introduction.rst
@@ -176,8 +176,14 @@ static file server in production without changing any code.
 
 Example: :ref:`static_assets_section`.
 
-Debug Toolbar
-~~~~~~~~~~~~~
+Fully Interactive Development
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When developing a Pyramid application, several interactive features are
+available.  Pyramid can automatically utilize changed templates when rendering
+pages and automatically restart the application to incorporate changed python
+code.  Plain old ``printf()`` calls used for debugging can display to a
+console.
 
 Pyramid's debug toolbar comes activated when you use a Pyramid scaffold to
 render a project.  This toolbar overlays your application in the browser, and
@@ -321,7 +327,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 +345,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:
@@ -777,7 +790,7 @@ automate some of the tedium away:
        for method in ('GET', 'POST', 'HEAD'):
            view = getattr(module, 'xhr_%s_view' % method, None)
            if view is not None:
-               config.add_view(view, route_name='xhr_route', xhr=True, 
+               config.add_view(view, route_name='xhr_route', xhr=True,
                               permission='view', request_method=method)
 
    config = Configurator()
diff --git a/docs/narr/project.rst b/docs/narr/project.rst
index 9451f41b1..8b7c24725 100644
--- a/docs/narr/project.rst
+++ b/docs/narr/project.rst
@@ -146,7 +146,7 @@ puts his projects in ``C:\projects``.
 
 .. warning::
 
-   You’ll need to avoid using ``pcreate`` to create a project with the same
+   You'll need to avoid using ``pcreate`` to create a project with the same
    name as a Python standard library component. In particular, this means you
    should avoid using the names ``site`` or ``test``, both of which
    conflict with Python standard library packages.  You should also avoid
@@ -243,16 +243,16 @@ Here's sample output from a test run on UNIX:
 
    OK
 
-.. note::
-
-   The ``-q`` option is passed to the ``setup.py test`` command to limit the
-   output to a stream of dots.  If you don't pass ``-q``, you'll see more
-   verbose test result output (which normally isn't very useful).
-
 The tests themselves are found in the ``tests.py`` module in your ``pcreate``
 generated project.  Within a project generated by the ``starter`` scaffold, a
 single sample test exists.
 
+.. note::
+
+    The ``-q`` option is passed to the ``setup.py test`` command to limit the
+    output to a stream of dots.  If you don't pass ``-q``, you'll see more
+    verbose test result output (which normally isn't very useful).
+
 .. index::
    single: running an application
    single: pserve
@@ -696,11 +696,11 @@ testing, packaging, and distributing your application.
 
 .. note::
 
-  ``setup.py`` is the de facto standard which Python developers use to
-  distribute their reusable code.  You can read more about ``setup.py`` files
-  and their usage in the `Setuptools documentation
-  <http://peak.telecommunity.com/DevCenter/setuptools>`_ and `The
-  Hitchhiker's Guide to Packaging <http://guide.python-distribute.org/>`_.
+    ``setup.py`` is the de facto standard which Python developers use to
+    distribute their reusable code.  You can read more about ``setup.py`` files
+    and their usage in the `Setuptools documentation
+    <http://peak.telecommunity.com/DevCenter/setuptools>`_ and `The
+    Hitchhiker's Guide to Packaging <http://guide.python-distribute.org/>`_.
 
 Our generated ``setup.py`` looks like this:
 
@@ -883,18 +883,28 @@ dictionary the view returns (on line 6) provides the value the renderer
 substitutes into the template when generating HTML.  The renderer then
 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:: Dictionaries provide values to :term:`template`\s.
+
+.. note:: ``development.ini`` has a setting that controls how templates are
+   reloaded, ``pyramid.reload_templates``.
+
+   - When set to ``True`` (as in the scaffold ``development.ini``) changed
+     templates automatically reload without a server restart.  This is
+     convenient while developing, but slows template rendering speed.
+
+   - When set to ``False`` (the default value), changing templates requires
+     a server restart to reload them.  Production applications should use
+     ``pyramid.reload_templates = False``.
+
+.. seealso:: See also :ref:`views_which_use_a_renderer` for more information
+    about how views, renderers, and templates relate and cooperate.
+
+.. seealso:: Pyramid can also dynamically reload changed Python files.  For
+    more on this see :ref:`reloading_code`.
 
-.. note:: Because our ``development.ini`` has a ``pyramid.reload_templates =
-   true`` directive indicating that templates should be reloaded when
-   they change, you won't need to restart the application server to
-   see changes you make to templates.  During development, this is
-   handy.  If this directive had been ``false`` (or if the directive
-   did not exist), you would need to restart the application server
-   for each template change.  For production applications, you should
-   set your project's ``pyramid.reload_templates`` to ``false`` to increase
-   the speed at which templates may be rendered.
+.. seealso:: The :ref:`debug_toolbar` provides interactive access to your
+   application's internals and, should an exception occur, allows interactive
+   access to traceback execution stack frames from the Python interpreter.
 
 .. index::
    single: static directory
@@ -974,9 +984,9 @@ named ``views`` instead of within a single ``views.py`` file, you might:
   can be empty.  This just tells Python that the ``views`` directory is a
   *package*.)
 
-- *Move* the existing ``views.py`` file to a file inside the new ``views``
-  directory named, say, ``blog.py``.  Because the ``templates`` directory
-  remains in the ``myproject`` package, the template :term:`asset
+- *Move* the content from the existing ``views.py`` file to a file inside the
+  new ``views`` directory named, say, ``blog.py``.  Because the ``templates``
+  directory remains in the ``myproject`` package, the template :term:`asset
   specification` values in ``blog.py`` must now be fully qualified with the
   project's package name (``myproject:templates/blog.pt``).
 
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)