Merge branch 'scafftween'

21 files changed, 109 insertions, 90 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-debug.png b/docs/narr/project-debug.png
new file mode 100644
index 000000000..d13a91736
--- /dev/null
+++ b/docs/narr/project-debug.png
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..baf4c86fa 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,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
@@ -419,8 +458,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 +526,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 +588,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
diff --git a/docs/tutorials/wiki/src/authorization/development.ini b/docs/tutorials/wiki/src/authorization/development.ini
index 07800514e..8c60f4ea9 100644
--- a/docs/tutorials/wiki/src/authorization/development.ini
+++ b/docs/tutorials/wiki/src/authorization/development.ini
@@ -6,20 +6,17 @@ pyramid.debug_notfound = false
 pyramid.debug_routematch = false
 pyramid.debug_templates = true
 pyramid.default_locale_name = en
+pyramid.include = pyramid_debugtoolbar
+                  pyramid_tm
+pyramid_tm.attempts = 3
+
 zodb_uri = file://%(here)s/Data.fs?connection_cache_size=20000
 
 [pipeline:main]
 pipeline =
-    egg:WebError#evalerror
     egg:repoze.zodbconn#closer
-    egg:repoze.retry#retry
-    tm
     tutorial
 
-[filter:tm]
-use = egg:repoze.tm2#tm
-commit_veto = repoze.tm:default_commit_veto
-
 [server:main]
 use = egg:Paste#http
 host = 0.0.0.0
diff --git a/docs/tutorials/wiki/src/authorization/production.ini b/docs/tutorials/wiki/src/authorization/production.ini
index 217bdd260..2cfca5f80 100644
--- a/docs/tutorials/wiki/src/authorization/production.ini
+++ b/docs/tutorials/wiki/src/authorization/production.ini
@@ -6,6 +6,9 @@ pyramid.debug_notfound = false
 pyramid.debug_routematch = false
 pyramid.debug_templates = false
 pyramid.default_locale_name = en
+pyramid.include = pyramid_tm
+pyramid_tm.attempts = 3
+
 zodb_uri = file://%(here)s/Data.fs?connection_cache_size=20000
 
 [filter:weberror]
@@ -22,16 +25,10 @@ debug = false
 ;smtp_use_tls =
 ;error_message =
 
-[filter:tm]
-use = egg:repoze.tm2#tm
-commit_veto = repoze.tm:default_commit_veto
-
 [pipeline:main]
 pipeline =
     weberror
     egg:repoze.zodbconn#closer
-    egg:repoze.retry#retry
-    tm
     tutorial
 
 [server:main]
diff --git a/docs/tutorials/wiki/src/authorization/setup.py b/docs/tutorials/wiki/src/authorization/setup.py
index adfa70c9f..f3b404516 100644
--- a/docs/tutorials/wiki/src/authorization/setup.py
+++ b/docs/tutorials/wiki/src/authorization/setup.py
@@ -9,8 +9,8 @@ CHANGES = open(os.path.join(here, 'CHANGES.txt')).read()
 requires = [
     'pyramid',
     'repoze.zodbconn',
-    'repoze.tm2>=1.0b1', # default_commit_veto
-    'repoze.retry',
+    'pyramid_tm',
+    'pyramid_debugtoolbar',
     'ZODB3',
     'WebError',
     'docutils',
diff --git a/docs/tutorials/wiki/src/basiclayout/development.ini b/docs/tutorials/wiki/src/basiclayout/development.ini
index 04e341f2e..3913f45db 100644
--- a/docs/tutorials/wiki/src/basiclayout/development.ini
+++ b/docs/tutorials/wiki/src/basiclayout/development.ini
@@ -6,20 +6,17 @@ pyramid.debug_notfound = false
 pyramid.debug_routematch = false
 pyramid.debug_templates = true
 pyramid.default_locale_name = en
+pyramid.include = pyramid_debugtoolbar
+                  pyramid_tm
+pyramid_tm.attempts = 3
+
 zodb_uri = file://%(here)s/Data.fs?connection_cache_size=20000
 
 [pipeline:main]
 pipeline =
-    egg:WebError#evalerror
     egg:repoze.zodbconn#closer
-    egg:repoze.retry#retry
-    tm
     tutorial
 
-[filter:tm]
-use = egg:repoze.tm2#tm
-commit_veto = repoze.tm:default_commit_veto
-
 [server:main]
 use = egg:Paste#http
 host = 0.0.0.0
diff --git a/docs/tutorials/wiki/src/basiclayout/production.ini b/docs/tutorials/wiki/src/basiclayout/production.ini
index 217bdd260..2cfca5f80 100644
--- a/docs/tutorials/wiki/src/basiclayout/production.ini
+++ b/docs/tutorials/wiki/src/basiclayout/production.ini
@@ -6,6 +6,9 @@ pyramid.debug_notfound = false
 pyramid.debug_routematch = false
 pyramid.debug_templates = false
 pyramid.default_locale_name = en
+pyramid.include = pyramid_tm
+pyramid_tm.attempts = 3
+
 zodb_uri = file://%(here)s/Data.fs?connection_cache_size=20000
 
 [filter:weberror]
@@ -22,16 +25,10 @@ debug = false
 ;smtp_use_tls =
 ;error_message =
 
-[filter:tm]
-use = egg:repoze.tm2#tm
-commit_veto = repoze.tm:default_commit_veto
-
 [pipeline:main]
 pipeline =
     weberror
     egg:repoze.zodbconn#closer
-    egg:repoze.retry#retry
-    tm
     tutorial
 
 [server:main]
diff --git a/docs/tutorials/wiki/src/basiclayout/setup.py b/docs/tutorials/wiki/src/basiclayout/setup.py
index 2d540d65b..31833dc7f 100644
--- a/docs/tutorials/wiki/src/basiclayout/setup.py
+++ b/docs/tutorials/wiki/src/basiclayout/setup.py
@@ -9,8 +9,8 @@ CHANGES = open(os.path.join(here, 'CHANGES.txt')).read()
 requires = [
     'pyramid',
     'repoze.zodbconn',
-    'repoze.tm2>=1.0b1', # default_commit_veto
-    'repoze.retry',
+    'pyramid_tm',
+    'pyramid_debugtoolbar',
     'ZODB3',
     'WebError',
     ]
diff --git a/docs/tutorials/wiki/src/models/development.ini b/docs/tutorials/wiki/src/models/development.ini
index 07800514e..8c60f4ea9 100644
--- a/docs/tutorials/wiki/src/models/development.ini
+++ b/docs/tutorials/wiki/src/models/development.ini
@@ -6,20 +6,17 @@ pyramid.debug_notfound = false
 pyramid.debug_routematch = false
 pyramid.debug_templates = true
 pyramid.default_locale_name = en
+pyramid.include = pyramid_debugtoolbar
+                  pyramid_tm
+pyramid_tm.attempts = 3
+
 zodb_uri = file://%(here)s/Data.fs?connection_cache_size=20000
 
 [pipeline:main]
 pipeline =
-    egg:WebError#evalerror
     egg:repoze.zodbconn#closer
-    egg:repoze.retry#retry
-    tm
     tutorial
 
-[filter:tm]
-use = egg:repoze.tm2#tm
-commit_veto = repoze.tm:default_commit_veto
-
 [server:main]
 use = egg:Paste#http
 host = 0.0.0.0
diff --git a/docs/tutorials/wiki/src/models/production.ini b/docs/tutorials/wiki/src/models/production.ini
index 217bdd260..2cfca5f80 100644
--- a/docs/tutorials/wiki/src/models/production.ini
+++ b/docs/tutorials/wiki/src/models/production.ini
@@ -6,6 +6,9 @@ pyramid.debug_notfound = false
 pyramid.debug_routematch = false
 pyramid.debug_templates = false
 pyramid.default_locale_name = en
+pyramid.include = pyramid_tm
+pyramid_tm.attempts = 3
+
 zodb_uri = file://%(here)s/Data.fs?connection_cache_size=20000
 
 [filter:weberror]
@@ -22,16 +25,10 @@ debug = false
 ;smtp_use_tls =
 ;error_message =
 
-[filter:tm]
-use = egg:repoze.tm2#tm
-commit_veto = repoze.tm:default_commit_veto
-
 [pipeline:main]
 pipeline =
     weberror
     egg:repoze.zodbconn#closer
-    egg:repoze.retry#retry
-    tm
     tutorial
 
 [server:main]
diff --git a/docs/tutorials/wiki/src/models/setup.py b/docs/tutorials/wiki/src/models/setup.py
index 2d540d65b..31833dc7f 100644
--- a/docs/tutorials/wiki/src/models/setup.py
+++ b/docs/tutorials/wiki/src/models/setup.py
@@ -9,8 +9,8 @@ CHANGES = open(os.path.join(here, 'CHANGES.txt')).read()
 requires = [
     'pyramid',
     'repoze.zodbconn',
-    'repoze.tm2>=1.0b1', # default_commit_veto
-    'repoze.retry',
+    'pyramid_tm',
+    'pyramid_debugtoolbar',
     'ZODB3',
     'WebError',
     ]
diff --git a/docs/tutorials/wiki/src/tests/development.ini b/docs/tutorials/wiki/src/tests/development.ini
index 07800514e..8c60f4ea9 100644
--- a/docs/tutorials/wiki/src/tests/development.ini
+++ b/docs/tutorials/wiki/src/tests/development.ini
@@ -6,20 +6,17 @@ pyramid.debug_notfound = false
 pyramid.debug_routematch = false
 pyramid.debug_templates = true
 pyramid.default_locale_name = en
+pyramid.include = pyramid_debugtoolbar
+                  pyramid_tm
+pyramid_tm.attempts = 3
+
 zodb_uri = file://%(here)s/Data.fs?connection_cache_size=20000
 
 [pipeline:main]
 pipeline =
-    egg:WebError#evalerror
     egg:repoze.zodbconn#closer
-    egg:repoze.retry#retry
-    tm
     tutorial
 
-[filter:tm]
-use = egg:repoze.tm2#tm
-commit_veto = repoze.tm:default_commit_veto
-
 [server:main]
 use = egg:Paste#http
 host = 0.0.0.0
diff --git a/docs/tutorials/wiki/src/tests/production.ini b/docs/tutorials/wiki/src/tests/production.ini
index 217bdd260..2cfca5f80 100644
--- a/docs/tutorials/wiki/src/tests/production.ini
+++ b/docs/tutorials/wiki/src/tests/production.ini
@@ -6,6 +6,9 @@ pyramid.debug_notfound = false
 pyramid.debug_routematch = false
 pyramid.debug_templates = false
 pyramid.default_locale_name = en
+pyramid.include = pyramid_tm
+pyramid_tm.attempts = 3
+
 zodb_uri = file://%(here)s/Data.fs?connection_cache_size=20000
 
 [filter:weberror]
@@ -22,16 +25,10 @@ debug = false
 ;smtp_use_tls =
 ;error_message =
 
-[filter:tm]
-use = egg:repoze.tm2#tm
-commit_veto = repoze.tm:default_commit_veto
-
 [pipeline:main]
 pipeline =
     weberror
     egg:repoze.zodbconn#closer
-    egg:repoze.retry#retry
-    tm
     tutorial
 
 [server:main]
diff --git a/docs/tutorials/wiki/src/tests/setup.py b/docs/tutorials/wiki/src/tests/setup.py
index d2c8f5697..603bb6bac 100644
--- a/docs/tutorials/wiki/src/tests/setup.py
+++ b/docs/tutorials/wiki/src/tests/setup.py
@@ -9,8 +9,8 @@ CHANGES = open(os.path.join(here, 'CHANGES.txt')).read()
 requires = [
     'pyramid',
     'repoze.zodbconn',
-    'repoze.tm2>=1.0b1',
-    'repoze.retry',
+    'pyramid_tm',
+    'pyramid_debugtoolbar',
     'ZODB3',
     'WebError',
     'docutils',
diff --git a/docs/tutorials/wiki/src/views/development.ini b/docs/tutorials/wiki/src/views/development.ini
index 04e341f2e..3913f45db 100644
--- a/docs/tutorials/wiki/src/views/development.ini
+++ b/docs/tutorials/wiki/src/views/development.ini
@@ -6,20 +6,17 @@ pyramid.debug_notfound = false
 pyramid.debug_routematch = false
 pyramid.debug_templates = true
 pyramid.default_locale_name = en
+pyramid.include = pyramid_debugtoolbar
+                  pyramid_tm
+pyramid_tm.attempts = 3
+
 zodb_uri = file://%(here)s/Data.fs?connection_cache_size=20000
 
 [pipeline:main]
 pipeline =
-    egg:WebError#evalerror
     egg:repoze.zodbconn#closer
-    egg:repoze.retry#retry
-    tm
     tutorial
 
-[filter:tm]
-use = egg:repoze.tm2#tm
-commit_veto = repoze.tm:default_commit_veto
-
 [server:main]
 use = egg:Paste#http
 host = 0.0.0.0
diff --git a/docs/tutorials/wiki/src/views/production.ini b/docs/tutorials/wiki/src/views/production.ini
index 217bdd260..2cfca5f80 100644
--- a/docs/tutorials/wiki/src/views/production.ini
+++ b/docs/tutorials/wiki/src/views/production.ini
@@ -6,6 +6,9 @@ pyramid.debug_notfound = false
 pyramid.debug_routematch = false
 pyramid.debug_templates = false
 pyramid.default_locale_name = en
+pyramid.include = pyramid_tm
+pyramid_tm.attempts = 3
+
 zodb_uri = file://%(here)s/Data.fs?connection_cache_size=20000
 
 [filter:weberror]
@@ -22,16 +25,10 @@ debug = false
 ;smtp_use_tls =
 ;error_message =
 
-[filter:tm]
-use = egg:repoze.tm2#tm
-commit_veto = repoze.tm:default_commit_veto
-
 [pipeline:main]
 pipeline =
     weberror
     egg:repoze.zodbconn#closer
-    egg:repoze.retry#retry
-    tm
     tutorial
 
 [server:main]
diff --git a/docs/tutorials/wiki/src/views/setup.py b/docs/tutorials/wiki/src/views/setup.py
index daa5e5eb1..6acc004c0 100644
--- a/docs/tutorials/wiki/src/views/setup.py
+++ b/docs/tutorials/wiki/src/views/setup.py
@@ -9,8 +9,8 @@ CHANGES = open(os.path.join(here, 'CHANGES.txt')).read()
 requires = [
     'pyramid',
     'repoze.zodbconn',
-    'repoze.tm2>=1.0b1', # default_commit_veto
-    'repoze.retry',
+    'pyramid_tm',
+    'pyramid_debugtoolbar',
     'ZODB3',
     'WebError',
     'docutils',