- straighten out difference between content and its presentation, re: admonitions of note, seealse, sidebar

1 files changed, 33 insertions, 46 deletions

diff --git a/docs/narr/project.rst b/docs/narr/project.rst
index b4397c09b..fcce9fac4 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
@@ -210,12 +210,6 @@ Python interpreter from the :term:`virtualenv` you created during
 :ref:`installing_chapter` (the ``python`` command that lives in the ``bin``
 directory of your virtualenv).
 
-.. sidebar:: Verbose Testing
-
-   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).
-
 On UNIX:
 
 .. code-block:: text
@@ -253,6 +247,12 @@ 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
@@ -684,14 +684,6 @@ use a different version control system, you may need to install a setuptools
 add-on such as ``setuptools-git`` or ``setuptools-hg`` for this behavior to
 work properly.
 
-.. sidebar:: Python's ``setup.py``
-
-  ``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/>`_.
-
 .. index::
    single: setup.py
 
@@ -702,6 +694,14 @@ The ``setup.py`` file is a :term:`setuptools` setup file.  It is meant to be
 run directly from the command line to perform a variety of functions, such as
 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/>`_.
+
 Our generated ``setup.py`` looks like this:
 
 .. literalinclude:: MyProject/setup.py
@@ -857,26 +857,6 @@ and which returns a :term:`response`.
    :language: python
    :linenos:
 
-.. sidebar:: Fully Interactive Development
-
-   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 template rendering speed.
-
-   Pyramid can also dynamically reload changed Python files.  For more
-   on this see :ref:`reloading_code` above.
-
-   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.
-
 Lines 4-6 define and register a :term:`view callable` named ``my_view``.  The
 function named ``my_view`` is decorated with a ``view_config`` decorator
 (which is processed by the ``config.scan()`` line in our ``__init__.py``).
@@ -905,20 +885,27 @@ returns the HTML in a :term:`response`.
 
 .. note:: Dictionaries provide values to :term:`template`\s.
 
-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
+   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`.
+
+.. 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