From c6d9f191e920536fdb274d15ef956a5e8151bbc2 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Tue, 9 Aug 2011 14:18:32 -0400 Subject: fix project.rst to deal with scaffold changes --- docs/narr/MyProject/development.ini | 3 ++- docs/narr/MyProject/production.ini | 1 + docs/narr/MyProject/setup.py | 2 +- docs/narr/project.png | Bin 84679 -> 128727 bytes docs/narr/project.rst | 51 +++++++++++++++++++++++++++--------- 5 files changed, 42 insertions(+), 15 deletions(-) (limited to 'docs') 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 Binary files a/docs/narr/project.png and b/docs/narr/project.png differ 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 +`_. + +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 -- cgit v1.2.3 From 06247f77d3a7f6757c6082badb00154b6f626922 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Tue, 9 Aug 2011 14:21:55 -0400 Subject: instructions about how to turn the toolbar off --- docs/narr/project.rst | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) (limited to 'docs') diff --git a/docs/narr/project.rst b/docs/narr/project.rst index b4a0e1d45..baf4c86fa 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -326,6 +326,28 @@ 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 -- cgit v1.2.3 From 7b771318141be700a5f4fd72dcafdd26d179211b Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Tue, 9 Aug 2011 14:22:09 -0400 Subject: add the debug image --- docs/narr/project-debug.png | Bin 0 -> 153807 bytes 1 file changed, 0 insertions(+), 0 deletions(-) create mode 100644 docs/narr/project-debug.png (limited to 'docs') diff --git a/docs/narr/project-debug.png b/docs/narr/project-debug.png new file mode 100644 index 000000000..d13a91736 Binary files /dev/null and b/docs/narr/project-debug.png differ -- cgit v1.2.3 From ace57ba6a0443bbe4cb03fb6543243654c97eefa Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Tue, 9 Aug 2011 21:09:40 -0400 Subject: convert tutorials to pyramid_tm+pyramid_debugtoolbar --- docs/tutorials/wiki/src/authorization/development.ini | 11 ++++------- docs/tutorials/wiki/src/authorization/production.ini | 9 +++------ docs/tutorials/wiki/src/authorization/setup.py | 4 ++-- docs/tutorials/wiki/src/basiclayout/development.ini | 11 ++++------- docs/tutorials/wiki/src/basiclayout/production.ini | 9 +++------ docs/tutorials/wiki/src/basiclayout/setup.py | 4 ++-- docs/tutorials/wiki/src/models/development.ini | 11 ++++------- docs/tutorials/wiki/src/models/production.ini | 9 +++------ docs/tutorials/wiki/src/models/setup.py | 4 ++-- docs/tutorials/wiki/src/tests/development.ini | 11 ++++------- docs/tutorials/wiki/src/tests/production.ini | 9 +++------ docs/tutorials/wiki/src/tests/setup.py | 4 ++-- docs/tutorials/wiki/src/views/development.ini | 11 ++++------- docs/tutorials/wiki/src/views/production.ini | 9 +++------ docs/tutorials/wiki/src/views/setup.py | 4 ++-- 15 files changed, 45 insertions(+), 75 deletions(-) (limited to 'docs') 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', -- cgit v1.2.3