fix project.rst to deal with scaffold changes

5 files changed, 42 insertions, 15 deletions

diff --git a/docs/narr/MyProject/development.ini b/docs/narr/MyProject/development.ini
index d0db3047c..1818e387b 100644
--- a/docs/narr/MyProject/development.ini
+++ b/docs/narr/MyProject/development.ini
@@ -1,15 +1,16 @@
 [app:MyProject]
 use = egg:MyProject
+
 pyramid.reload_templates = true
 pyramid.debug_authorization = false
 pyramid.debug_notfound = false
 pyramid.debug_routematch = false
 pyramid.debug_templates = true
 pyramid.default_locale_name = en
+pyramid.include = pyramid_debugtoolbar
 
 [pipeline:main]
 pipeline =
-    egg:WebError#evalerror
     MyProject
 
 [server:main]
diff --git a/docs/narr/MyProject/production.ini b/docs/narr/MyProject/production.ini
index d0ed9628c..7a5674d23 100644
--- a/docs/narr/MyProject/production.ini
+++ b/docs/narr/MyProject/production.ini
@@ -1,5 +1,6 @@
 [app:MyProject]
 use = egg:MyProject
+
 pyramid.reload_templates = false
 pyramid.debug_authorization = false
 pyramid.debug_notfound = false
diff --git a/docs/narr/MyProject/setup.py b/docs/narr/MyProject/setup.py
index a64d65ba6..a0b6fab9e 100644
--- a/docs/narr/MyProject/setup.py
+++ b/docs/narr/MyProject/setup.py
@@ -6,7 +6,7 @@ here = os.path.abspath(os.path.dirname(__file__))
 README = open(os.path.join(here, 'README.txt')).read()
 CHANGES = open(os.path.join(here, 'CHANGES.txt')).read()
 
-requires = ['pyramid', 'WebError']
+requires = ['pyramid', 'pyramid_debugtoolbar', 'WebError']
 
 setup(name='MyProject',
       version='0.0',
diff --git a/docs/narr/project.png b/docs/narr/project.png
index da5bc870b..fc00ec086 100644
--- a/docs/narr/project.png
+++ b/docs/narr/project.png
diff --git a/docs/narr/project.rst b/docs/narr/project.rst
index 3b1b45eda..b4a0e1d45 100644
--- a/docs/narr/project.rst
+++ b/docs/narr/project.rst
@@ -99,18 +99,18 @@ We'll choose the ``pyramid_starter`` scaffold for this purpose.
 
    $ bin/paster create -t pyramid_starter
 
-The above command uses the ``paster create`` command to create a project with the
-``pyramid_starter`` 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
 
@@ -309,6 +309,23 @@ 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.
+
 .. sidebar:: Using an Alternate WSGI Server
 
    The code generated by a :app:`Pyramid` scaffold assumes that you
@@ -419,8 +436,6 @@ 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:
@@ -489,6 +504,14 @@ information.
    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
 :ref:`environment_chapter` for more information about these settings.
@@ -543,11 +566,13 @@ implementations.
 
 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