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

1 files changed, 36 insertions, 26 deletions

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``).