fix merge conflicts

1 files changed, 118 insertions, 137 deletions

diff --git a/docs/narr/project.rst b/docs/narr/project.rst
index 631412f42..baf4c86fa 100644
--- a/docs/narr/project.rst
+++ b/docs/narr/project.rst
@@ -12,9 +12,9 @@ A project is a directory that contains at least one Python :term:`package`.
 You'll use a scaffold to create a project, and you'll create your application
 logic within a package that lives inside the project.  Even if your
 application is extremely simple, it is useful to place code that drives the
-application within a package, because a package is more easily extended with
-new code.  An application that lives inside a package can also be distributed
-more easily than one which does not live within a package.
+application within a package, because: 1) a package is more easily extended
+with new code and 2) an application that lives inside a package can also be
+distributed more easily than one which does not live within a package.
 
 :app:`Pyramid` comes with a variety of scaffolds that you can use to generate
 a project.  Each scaffold makes different configuration assumptions about
@@ -99,19 +99,18 @@ We'll choose the ``pyramid_starter`` scaffold for this purpose.
 
    $ bin/paster create -t pyramid_starter
 
-The above command uses the ``paster`` command to create a project using the
-``pyramid_starter`` scaffold.  The ``paster create`` command creates project
-from a scaffold.  To use a different scaffold, such as
+The above command uses the ``paster create`` command to create a project with
+the ``pyramid_starter`` scaffold.  To use a different scaffold, such as
 ``pyramid_routesalchemy``, you'd just change the last argument.  For example:
 
 .. code-block:: text
 
    $ bin/paster create -t pyramid_routesalchemy
 
-``paster create`` will ask you a single question: the *name* of the
-project.  You should use a string without spaces and with only letters
-in it.  Here's sample output from a run of ``paster create`` for a
-project we name ``MyProject``:
+``paster create`` will ask you a single question: the *name* of the project.
+You should use a string without spaces and with only letters in it.  Here's
+sample output from a run of ``paster create`` for a project we name
+``MyProject``:
 
 .. code-block:: text
 
@@ -177,7 +176,7 @@ command ``python setup.py develop``
 The file named ``setup.py`` will be in the root of the paster-generated
 project directory.  The ``python`` you're invoking should be the one that
 lives in the ``bin`` directory of your virtual Python environment.  Your
-terminal's current working directory *must* the the newly created project
+terminal's current working directory *must* be the newly created project
 directory.  For example:
 
 .. code-block:: text
@@ -194,7 +193,8 @@ Elided output from a run of this command is shown below:
 
 This will install a :term:`distribution` representing your project into the
 interpreter's library set so it can be found by ``import`` statements and by
-:term:`PasteDeploy` commands such as ``paster serve`` and ``paster pshell``.
+:term:`PasteDeploy` commands such as ``paster serve``, ``paster pshell``,
+``paster proutes`` and ``paster pviews``.
 
 .. index::
    single: running tests
@@ -244,115 +244,10 @@ create`` -generated project.  Within a project generated by the
 ``pyramid_starter`` scaffold, a single sample test exists.
 
 .. index::
-   single: interactive shell
-   single: IPython
-   single: paster pshell
-
-.. _interactive_shell:
-
-The Interactive Shell
----------------------
-
-Once you've installed your program for development using ``setup.py
-develop``, you can use an interactive Python shell to examine your
-:app:`Pyramid` project's :term:`resource` and :term:`view` objects from a
-Python prompt.  To do so, use your virtualenv's ``paster pshell`` command.
-
-The first argument to ``pshell`` is the path to your application's ``.ini``
-file.  The second is the ``app`` section name inside the ``.ini`` file which
-points to *your application* as opposed to any other section within the
-``.ini`` file.  For example, if your application ``.ini`` file might have a
-``[app:MyProject]`` section that looks like so:
-
-.. code-block:: ini
-   :linenos:
-
-   [app:MyProject]
-   use = egg:MyProject
-   reload_templates = true
-   debug_authorization = false
-   debug_notfound = false
-   debug_templates = true
-   default_locale_name = en
-
-If so, you can use the following command to invoke a debug shell using the
-name ``MyProject`` as a section name:
-
-.. code-block:: text
-
-   [chrism@vitaminf shellenv]$ ../bin/paster pshell development.ini MyProject
-   Python 2.4.5 (#1, Aug 29 2008, 12:27:37)
-   [GCC 4.0.1 (Apple Inc. build 5465)] on darwin
-   Type "help" for more information. "root" is the Pyramid app root object,
-   "registry" is the Pyramid registry object.
-   >>> root
-   <myproject.resources.MyResource object at 0x445270>
-   >>> registry
-   <Registry myproject>
-   >>> registry.settings['debug_notfound']
-   False
-   >>> from myproject.views import my_view
-   >>> from pyramid.request import Request
-   >>> r = Request.blank('/')
-   >>> my_view(r)
-   {'project': 'myproject'}
-
-Two names are made available to the pshell user as globals: ``root`` and
-``registry``.  ``root`` is the the object returned by the default :term:`root
-factory` in your application.  ``registry`` is the :term:`application
-registry` object associated with your project's application (often accessed
-within view code as ``request.registry``).
-
-If you have `IPython <http://en.wikipedia.org/wiki/IPython>`_ installed in
-the interpreter you use to invoke the ``paster`` command, the ``pshell``
-command will use an IPython interactive shell instead of a standard Python
-interpreter shell.  If you don't want this to happen, even if you have
-IPython installed, you can pass the ``--disable-ipython`` flag to the
-``pshell`` command to use a standard Python interpreter shell
-unconditionally.
-
-.. code-block:: text
-
-   [chrism@vitaminf shellenv]$ ../bin/paster pshell --disable-ipython \
-                                development.ini MyProject
-
-You should always use a section name argument that refers to the actual
-``app`` section within the Paste configuration file that points at your
-:app:`Pyramid` application *without any middleware wrapping*.  In particular,
-a section name is inappropriate as the second argument to ``pshell`` if the
-configuration section it names is a ``pipeline`` rather than an ``app``.  For
-example, if you have the following ``.ini`` file content:
-
-.. code-block:: ini
-   :linenos:
-
-   [app:MyProject]
-   use = egg:MyProject
-   reload_templates = true
-   debug_authorization = false
-   debug_notfound = false
-   debug_templates = true
-   default_locale_name = en
-
-   [pipeline:main]
-   pipeline =
-       egg:WebError#evalerror
-       MyProject
-
-Use ``MyProject`` instead of ``main`` as the section name argument to
-``pshell`` against the above ``.ini`` file (e.g. ``paster pshell
-development.ini MyProject``).  If you use ``main`` instead, an error will
-occur.  Use the most specific reference to your application within the
-``.ini`` file possible as the section name argument.
-
-Press ``Ctrl-D`` to exit the interactive shell (or ``Ctrl-Z`` on Windows).
-
-.. index::
    single: running an application
    single: paster serve
    single: reload
    single: startup
-   single: mod_wsgi
 
 Running The Project Application
 -------------------------------
@@ -398,6 +293,10 @@ For more detailed information about the startup process, see
 configuration file settings that influence startup and runtime behavior, see
 :ref:`environment_chapter`.
 
+.. index::
+   single: mod_wsgi
+   single: WSGI
+
 Viewing the Application
 -----------------------
 
@@ -410,6 +309,45 @@ browser like what is displayed in the following image:
 This is the page shown by default when you visit an unmodified ``paster
 create`` -generated ``pyramid_starter`` application in a browser.
 
+If you click on the image shown at the right hand top of the page ("^DT"),
+you'll be presented with a debug toolbar that provides various niceties while
+you're developing.  This image will float above every HTML page served by
+:app:`Pyramid` while you develop an application, and allows you show the
+toolbar as necessary.  Click on ``Hide`` to hide the toolbar and show the
+image again.
+
+.. image:: project-debug.png
+
+For more information about what the debug toolbar allows you to do, see `the
+documentation for pyramid_debugtoolbar
+<http://docs.pylonsproject.org/projects/pyramid_debugtoolbar/dev/>`_.
+
+The debug toolbar will not be shown (and all debugging will be turned off)
+when you use the ``production.ini`` file instead of the ``development.ini``
+ini file to run the application.
+
+You can also turn the debug toolbar off by editing ``development.ini`` and
+commenting out the line ``pyramid.include = pyramid_debugtoolbar``.  For
+example, instead of:
+
+.. code-block:: ini
+   :linenos:
+
+   [app:MyApp]
+   ...
+   pyramid.include = pyramid_debugtoolbar
+
+Put a hash mark in front of the ``pyramid.include`` line:
+
+.. code-block:: ini
+   :linenos:
+
+   [app:MyApp]
+   ...
+   #pyramid.include = pyramid_debugtoolbar
+
+Then restart the application to see that the toolbar has been turned off.
+
 .. sidebar:: Using an Alternate WSGI Server
 
    The code generated by a :app:`Pyramid` scaffold assumes that you
@@ -520,14 +458,13 @@ serve``, as well as the deployment settings provided to that application.
 
 The generated ``development.ini`` file looks like so:
 
-.. latexbroken?
-
 .. literalinclude:: MyProject/development.ini
    :language: ini
    :linenos:
 
 This file contains several "sections" including ``[app:MyProject]``,
-``[pipeline:main]``, and ``[server:main]``.
+``[pipeline:main]``, ``[server:main]`` and several other sections related to
+logging configuration.
 
 The ``[app:MyProject]`` section represents configuration for your
 application.  This section name represents the ``MyProject`` application (and
@@ -558,7 +495,7 @@ the default.
    point can thus be referred to as a "Paste application factory in the
    ``MyProject`` project which has the entry point named ``main`` where the
    entry point refers to a ``main`` function in the ``mypackage`` module".
-   If indeed if you open up the ``__init__.py`` module generated within the
+   Indeed, if you open up the ``__init__.py`` module generated within the
    ``myproject`` package, you'll see a ``main`` function.  This is the
    function called by :term:`PasteDeploy` when the ``paster serve`` command
    is invoked against our application.  It accepts a global configuration
@@ -567,27 +504,35 @@ the default.
 The ``use`` setting is the only setting *required* in the ``[app:MyProject]``
 section unless you've changed the callable referred to by the
 ``egg:MyProject`` entry point to accept more arguments: other settings you
-add to this section are passed as keywords arguments to the callable
+add to this section are passed as keyword arguments to the callable
 represented by this entry point (``main`` in our ``__init__.py`` module).
 You can provide startup-time configuration parameters to your application by
 adding more settings to this section.
 
-The ``reload_templates`` setting in the ``[app:MyProject]`` section is a
-:app:`Pyramid` -specific setting which is passed into the framework.  If it
+The ``pyramid.reload_templates`` setting in the ``[app:MyProject]`` section is
+a :app:`Pyramid` -specific setting which is passed into the framework.  If it
 exists, and its value is ``true``, :term:`Chameleon` and :term:`Mako`
 template changes will not require an application restart to be detected.  See
 :ref:`reload_templates_section` for more information.
 
-The ``debug_templates`` setting in the ``[app:MyProject]`` section is a
+The ``pyramid.debug_templates`` setting in the ``[app:MyProject]`` section is a
 :app:`Pyramid` -specific setting which is passed into the framework.  If it
 exists, and its value is ``true``, :term:`Chameleon` template exceptions will
-contained more detailed and helpful information about the error than when
+contain more detailed and helpful information about the error than when
 this value is ``false``.  See :ref:`debug_templates_section` for more
 information.
 
-.. warning:: The ``reload_templates`` and ``debug_templates`` options should
-   be turned off for production applications, as template rendering is slowed
-   when either is turned on.
+.. warning:: The ``pyramid.reload_templates`` and ``pyramid.debug_templates``
+   options should be turned off for production applications, as template
+   rendering is slowed when either is turned on.
+
+The ``pyramid.include`` setting in the ``[app:MyProject]`` section tells
+Pyramid to "include" configuration from another package.  In this case, the
+line ``pyramid.include = pyramid_debugtoolbar`` tells Pyramid to include
+configuration from the ``pyramid_debugtoolbar`` package.  This turns on a
+debugging panel in development mode which will be shown on the right hand
+side of the screen.  Including the debug toolbar will also make it possible
+to interactively debug exceptions when an error occurs.
 
 Various other settings may exist in this section having to do with debugging
 or influencing runtime behavior of a :app:`Pyramid` application.  See
@@ -611,6 +556,16 @@ for each request.
   application be nonblocking as all application code will run in its own
   thread, provided by the server you're using.
 
+The sections that live between the markers ``# Begin logging configuration``
+and ``# End logging configuration`` represent Python's standard library
+:mod:`logging` module configuration for your application.  The sections
+between these two markers are passed to the `logging module's config file
+configuration engine
+<http://docs.python.org/howto/logging.html#configuring-logging>`_ when the
+``paster serve`` or ``paster pshell`` commands are executed.  The default
+configuration sends application logging output to the standard error output
+of your terminal.
+
 See the :term:`PasteDeploy` documentation for more information about other
 types of things you can put into this ``.ini`` file, such as other
 applications, :term:`middleware` and alternate :term:`WSGI` server
@@ -625,16 +580,21 @@ implementations.
    to your application's ``main`` function as ``global_config`` (see
    the reference to the ``main`` function in :ref:`init_py`).
 
+.. index::
+   single: production.ini
+
 ``production.ini``
 ~~~~~~~~~~~~~~~~~~~
 
 The ``production.ini`` file is a :term:`PasteDeploy` configuration file with
 a purpose much like that of ``development.ini``.  However, it disables the
-WebError interactive debugger, replacing it with a logger which outputs
-exception messages to ``stderr`` by default.  It also turns off template
-development options such that templates are not automatically reloaded when
-changed, and turns off all debugging options.  You can use this file instead
-of ``development.ini`` when you put your application into production.
+debug toolbar, replacing it with a logger which outputs exception messages to
+``stderr`` by default.  It also turns off template development options such
+that templates are not automatically reloaded when changed, and turns off all
+debugging options.  It allows you to configure a ``weberror#error_catcher``
+section that will cause exceptions to be sent to an email address when they
+are uncaught.  You can use this file instead of ``development.ini`` when you
+put your application into production.
 
 .. index::
    single: MANIFEST.in
@@ -750,6 +710,9 @@ who want to use your application.
    setuptools add-on such as ``setuptools-git`` or ``setuptools-hg`` for this
    behavior to work properly.
 
+.. index::
+   single: setup.cfg
+
 ``setup.cfg``
 ~~~~~~~~~~~~~
 
@@ -845,6 +808,9 @@ also informs Python that the directory which contains it is a *package*.
    Line 12 returns a :term:`WSGI` application to the caller of the function
    (Paste).
 
+.. index::
+   single: views.py
+
 ``views.py``
 ~~~~~~~~~~~~
 
@@ -876,14 +842,14 @@ file call to ``add_view``).
 See :ref:`views_which_use_a_renderer` for more information about how views,
 renderers, and templates relate and cooperate.
 
-.. note:: Because our ``development.ini`` has a ``reload_templates =
+.. 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 ``reload_templates`` to ``false`` to increase
+   set your project's ``pyramid.reload_templates`` to ``false`` to increase
    the speed at which templates may be rendered.
 
 .. index::
@@ -915,6 +881,9 @@ about which sort of data storage you'll want to use, so the sample
 application uses an instance of :class:`myproject.resources.Root` to
 represent the root.
 
+.. index::
+   single: static directory
+
 ``static``
 ~~~~~~~~~~
 
@@ -924,7 +893,7 @@ template.  It includes CSS and images.
 ``templates/mytemplate.pt``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The single :term:`Chameleon` template exists in the project.  Its contents
+The single :term:`Chameleon` template that exists in the project.  Its contents
 are too long to show here, but it displays a default page when rendered.  It
 is referenced by the call to ``add_view`` as the ``renderer`` attribute in
 the ``__init__`` file.  See :ref:`views_which_use_a_renderer` for more
@@ -955,6 +924,9 @@ example.
 See :ref:`testing_chapter` for more information about writing :app:`Pyramid`
 unit tests.
 
+.. index::
+   pair: modifying; package structure
+
 .. _modifying_package_structure:
 
 Modifying Package Structure
@@ -1024,4 +996,13 @@ This pattern can be used to rearrage code referred to by any Pyramid API
 argument which accepts a :term:`dotted Python name` or direct object
 reference.
 
+Using the Interactive Shell
+---------------------------
+
+It is possible to use a Python interpreter prompt loaded with a similar
+configuration as would be loaded if you were running your Pyramid application
+via ``paster serve``.  This can be a useful debugging tool.  See
+:ref:`interactive_shell` for more details.
+
+