Merge branch 'docs.quicktutorial'

1 files changed, 87 insertions, 0 deletions

diff --git a/docs/quick_tutorial/debugtoolbar.rst b/docs/quick_tutorial/debugtoolbar.rst
new file mode 100644
index 000000000..a5dd14ba1
--- /dev/null
+++ b/docs/quick_tutorial/debugtoolbar.rst
@@ -0,0 +1,87 @@
+============================================
+04: Easier Development with ``debugtoolbar``
+============================================
+
+Error-handling and introspection using the ``pyramid_debugtoolbar``
+add-on.
+
+Background
+==========
+
+As we introduce the basics we also want to show how to be productive in
+development and debugging. For example, we just discussed template
+reloading and earlier we showed ``--reload`` for application reloading.
+
+``pyramid_debugtoolbar`` is a popular Pyramid add-on which makes
+several tools available in your browser. Adding it to your project
+illustrates several points about configuration.
+
+Objectives
+==========
+
+- Install and enable the toolbar to help during development
+
+- Explain Pyramid add-ons
+
+- Show how an add-on gets configured into your application
+
+Steps
+=====
+
+#. First we copy the results of the previous step, as well as install
+   the ``pyramid_debugtoolbar`` package:
+
+   .. code-block:: bash
+
+    (venv)$ cd ..; cp -r ini debugtoolbar; cd debugtoolbar
+    (venv)$ python setup.py develop
+    (venv)$ easy_install pyramid_debugtoolbar
+
+
+#. Our ``debugtoolbar/development.ini`` gets a configuration entry for
+   ``pyramid.includes``:
+
+   .. literalinclude:: debugtoolbar/development.ini
+    :language: ini
+    :linenos:
+
+#. Run the WSGI application with:
+
+   .. code-block:: bash
+
+    (venv)$ pserve development.ini --reload
+
+#. Open http://localhost:6543/ in your browser. See the handy
+   toolbar on the right.
+
+Analysis
+========
+
+``pyramid_debugtoolbar`` is a full-fledged Python package,
+available on PyPI just like thousands of other Python packages. Thus we
+start by installing the ``pyramid_debugtoolbar`` package into our
+virtual environment using normal Python package installation commands.
+
+The ``pyramid_debugtoolbar`` Python package is also a Pyramid add-on,
+which means we need to include its add-on configuration into our web
+application. We could do this with imperative configuration in
+``tutorial/__init__.py`` by using ``config.include``. Pyramid also
+supports wiring in add-on configuration via our ``development.ini``
+using ``pyramid.includes``. We use this to load the configuration for
+the debugtoolbar.
+
+You'll now see an attractive (and collapsible) menu in the right of
+your browser, providing introspective access to debugging information.
+Even better, if your web application generates an error,
+you will see a nice traceback on the screen. When you want to disable
+this toolbar, no need to change code: you can remove it from
+``pyramid.includes`` in the relevant ``.ini`` configuration file (thus
+showing why configuration files are handy.)
+
+Note that the toolbar mutates the HTML generated by our app and uses jQuery to
+overlay itself.  If you are using the toolbar while you're developing and you
+start to experience otherwise inexplicable client-side weirdness, you can shut
+it off by commenting out the ``pyramid_debugtoolbar`` line in
+``pyramid.includes`` temporarily.
+
+.. seealso:: See Also: :ref:`pyramid_debugtoolbar <toolbar:overview>`