1 files changed, 69 insertions, 0 deletions
diff --git a/docs/narr/templates.rst b/docs/narr/templates.rst
index 23a1460a1..fc0f38b0f 100644
--- a/docs/narr/templates.rst
+++ b/docs/narr/templates.rst
@@ -501,6 +501,75 @@ application's configuration section, e.g.::
   use = egg:MyProject#app
   reload_templates = true
 
+.. _debug_templates_section:
+
+Nicer Exceptions in Templates
+-----------------------------
+
+The exceptions raised by Chameleon templates when a rendering fails
+are sometimes less than helpful.  :mod:`repoze.bfg` allows you to
+configure your application development environment so that exceptions
+generated by Chameleon during template compilation and execution will
+contain nicer debugging information.
+
+.. warning:: template-debugging behavior is not recommended for
+             production sites as it slows renderings; it's usually
+             only desirable during development.
+
+In order to turn on template exception debugging, you can use an
+environment variable setting or a configuration file setting.
+
+To use an environment variable, start your application under a shell
+using the ``BFG_DEBUG_TEMPLATES`` operating system environment
+variable set to ``1``, For example::
+
+  $ BFG_DEBUG_TEMPLATES=1 bin/paster serve myproject.ini
+
+To use a setting in the application ``.ini`` file for the same
+purpose, set the ``debug_templates`` key to ``true`` within the
+application's configuration section, e.g.::
+
+  [app:main]
+  use = egg:MyProject#app
+  debug_templates = true
+
+With template debugging off, a :exc:`NameError` exception resulting
+from rendering a template with an undefined variable
+(e.g. ``${wrong}``) might end like this::
+
+  File "/home/fred/env/lib/python2.5/site-packages/Chameleon-1.2.3-py2.5.egg/chameleon/core/utils.py", line 332, in __getitem__
+    raise NameError(key)
+  NameError: wrong
+
+Note that the exception has no information about which template was
+being rendered when the error occured.  But with template debugging
+on, an exception resulting from the same problem might end like so::
+
+    RuntimeError: Caught exception rendering template.
+     - Expression: ``wrong``
+     - Filename:   /home/fred/env/bfgzodb/bfgzodb/templates/mytemplate.pt
+     - Arguments:  renderer_name: bfgzodb:templates/mytemplate.pt
+                   template: <PageTemplateFile - at 0x1d2ecf0>
+                   xincludes: <XIncludes - at 0x1d3a130>
+                   request: <Request - at 0x1d2ecd0>
+                   project: bfgzodb
+                   macros: <Macros - at 0x1d3aed0>
+                   context: <MyModel None at 0x1d39130>
+                   view: <function my_view at 0x1d23570>
+
+    NameError: wrong
+
+The latter tells you which template the error occurred in, as well as
+displaying the arguments passed to the template itself.
+
+.. note::
+
+   Turning on ``debug_templates`` has the same effect as using the
+   Chameleon environment variable ``CHAMELEON_DEBUG``.  See `Chameleon
+   Environment Variables
+   <http://chameleon.repoze.org/docs/latest/config.html#environment-variables>`_
+   for more information.
+
 .. index::
    single: template internationalization
    single: internationalization (of templates)