diff --git a/_themes b/_themes
index 03e5e5a..17d997d 160000
--- a/_themes
+++ b/_themes
@@ -1 +1 @@
-Subproject commit 03e5e5aaaeddc4c9aea887478c7e7b379a127b6f
+Subproject commit 17d997df279e224cb6f7bbf28c257f840eabb69b
diff --git a/chameleon_i18n.rst b/chameleon_i18n.rst
index 75de9e7..785d1ec 100644
--- a/chameleon_i18n.rst
+++ b/chameleon_i18n.rst
@@ -59,6 +59,7 @@ Well, let's translate some parts of the given template ``mytemplate.pt``. Add a
namespace and an i18n:domain to the tag:
.. code-block:: text
+
-
+Search documentation
+ Search documentation
diff --git a/debugging.rst b/debugging.rst
index 47eda43..096c80c 100644
--- a/debugging.rst
+++ b/debugging.rst
@@ -1,5 +1,5 @@
Debugging
----------
+=========
Using PDB to Debug Your Application
+++++++++++++++++++++++++++++++++++
@@ -19,3 +19,129 @@ application, and that point in your code is reached, you will be dropped into
the ``pdb`` debugging console within the terminal that you used to start your
application.
+Below is a debugging scenario using PDB to debug Pyramid.
+
+Debugging Pyramid
++++++++++++++++++
+
+This tutorial provides a brief introduction to using the python
+debugger (``pdb``) for debugging pyramid applications.
+
+This scenario assume you've created a Pyramid project already. The scenario
+assumes you've created a Pyramid project named ``buggy`` using the
+``alchemy`` scaffold.
+
+Introducing PDB
+---------------
+
+- This single line of python is your new friend::
+
+ import pdb; pdb.set_trace()
+
+- As valid python, that can be inserted practically anywhere in a Python
+ source file. When the python interpreter hits it - execution will be
+ suspended providing you with interactive control from the parent TTY.
+
+PDB Commands
+------------
+
+- pdb exposes a number of standard interactive debugging
+ commands, including::
+
+ Documented commands (type help ):
+ ========================================
+ EOF bt cont enable jump pp run unt
+ a c continue exit l q s until
+ alias cl d h list quit step up
+ args clear debug help n r tbreak w
+ b commands disable ignore next restart u whatis
+ break condition down j p return unalias where
+
+ Miscellaneous help topics:
+ ==========================
+ exec pdb
+
+ Undocumented commands:
+ ======================
+ retval rv
+
+Debugging Our ``buggy`` App
+---------------------------
+
+- Back to our demo ``buggy`` application we generated from the ``alchemy``
+ scaffold, lets see if we can learn anything debugging it.
+
+- The traversal documentation describes how pyramid first acquires a root
+ object, and then descends the resource tree using the ``__getitem__`` for
+ each respective resource.
+
+Huh?
+----
+
+- Let's drop a pdb statement into our root factory object's ``__getitem__``
+ method and have a look. Edit the project's ``models.py`` and add the
+ aforementioned ``pdb`` line in ``MyModel.__getitem__``
+
+ .. code-block:: python
+
+ def __getitem__(self, key):
+ import pdb; pdb.set_trace()
+ session = DBSession()
+ # ...
+
+- Restart the Pyramid application, and request a page. Note the request
+ requires a path to hit our break-point::
+
+ http://localhost:6543/ <- misses the break-point, no traversal
+ http://localhost:6543/1 <- should find an object
+ http://localhost:6543/2 <- does not
+
+- For a very simple case, attempt to insert a missing key by default. Set
+ item to a valid new MyModel in ``MyRoot.__getitem__`` if a match isn't
+ found in the database
+
+ .. code-block:: python
+
+ item = session.query(MyModel).get(id)
+ if item is None:
+ item = MyModel(name='test %d'%id, value=str(id)) # naive insertion
+
+- Move the break-point within the if clause to avoid the false positive hits
+
+ .. code-block:: python
+
+ if item is None:
+ import pdb; pdb.set_trace()
+ item = MyModel(name='test %d'%id, value=str(id)) # naive insertion
+
+- Run again, note multiple request to the same id continue to create
+ new MyModel instances. That's not right!
+
+- Ah, of course, we forgot to add the new item to the session. Another line
+ added to our ``__getitem__`` method
+
+ .. code-block:: python
+
+ if item is None:
+ import pdb; pdb.set_trace()
+ item = MyModel(name='test %d'%id, value=str(id))
+ session.add(item)
+
+- Restart and test. Observe the stack; debug again. Examine the item
+ returning from MyModel::
+
+ (pdb) session.query(MyModel).get(id)
+
+- Finally, we realize the item.id needs to be set as well before adding
+
+ .. code-block:: python
+
+ if item is None:
+ item = MyModel(name='test %d'%id, value=str(id))
+ item.id = id
+ session.add(item)
+
+- Many great resources can be found describing the details of using
+ pdb. Try the interactive ``help`` (hit 'h') or a search engine near
+ you.
+
diff --git a/index.rst b/index.rst
index 4db6ad8..77f0ebd 100644
--- a/index.rst
+++ b/index.rst
@@ -10,6 +10,7 @@ The Pyramid Cookbook presents topical, practical usages of :mod:`Pyramid`.
files
exceptions
authentication
+ deployment
wiki2_auth
templates
catalog
@@ -22,6 +23,7 @@ The Pyramid Cookbook presents topical, practical usages of :mod:`Pyramid`.
zeo
configuration
events
+ chameleon_i18n
deployment/index.rst
porting
testing