- It is now possible to turn on Chameleon template "debugging mode"

  for all Chameleon BFG templates by setting a BFG-related Paster
  ``.ini`` file setting named ``debug_templates``. The exceptions
  raised by Chameleon templates when a rendering fails are sometimes
  less than helpful.  ``debug_templates`` allows you to configure your
  application development environment so that exceptions generated by
  Chameleon during template compilation and execution will contain
  more helpful debugging information.  This mode is on by default in
  all new projects.

12 files changed, 125 insertions, 11 deletions

diff --git a/CHANGES.txt b/CHANGES.txt
index 5d17d0134..e2199614f 100644
--- a/CHANGES.txt
+++ b/CHANGES.txt
@@ -62,10 +62,20 @@ Features
   narrative documentation chapter entitled ``Internationalization and
   Localization``.
 
-- A new setting named ``default_locale_name`` was added.  If this
-  string is present as a Paster ``.ini`` file option, it will be
-  considered the default locale name.  The default locale name is used
-  during locale-related operations such as language translation.
+- A new deployment setting named ``default_locale_name`` was added.
+  If this string is present as a Paster ``.ini`` file option, it will
+  be considered the default locale name.  The default locale name is
+  used during locale-related operations such as language translation.
+
+- It is now possible to turn on Chameleon template "debugging mode"
+  for all Chameleon BFG templates by setting a BFG-related Paster
+  ``.ini`` file setting named ``debug_templates``. The exceptions
+  raised by Chameleon templates when a rendering fails are sometimes
+  less than helpful.  ``debug_templates`` allows you to configure your
+  application development environment so that exceptions generated by
+  Chameleon during template compilation and execution will contain
+  more helpful debugging information.  This mode is on by default in
+  all new projects.
 
 ZCML
 ----
@@ -141,6 +151,9 @@ Paster Templates
 - A ``default_locale_name = en`` setting was added to each existing paster
   template.
 
+- A ``debug_templates = true`` setting was added to each existing
+  paster template.
+
 Licensing
 ---------
 
diff --git a/TODO.txt b/TODO.txt
index c38fa03f9..ff4a3373f 100644
--- a/TODO.txt
+++ b/TODO.txt
@@ -5,11 +5,6 @@
 
 - Basic WSGI documentation (pipeline / app / server).
 
-- Allow a debug argument to be supplied for template rendering
-  (requires Chameleon capable of accepting the ``debug`` argument to a
-  template constructor; behavior currently implemented on Chameleon
-  head but not in any release).
-
 - Figure out a way to expose some of the functionality of
   ``Configurator._derive_view`` as an API.
 
@@ -20,3 +15,4 @@
 
 - Fix message catalog extraction / compilation documentation.
 
+- Docs about creating a venusian decorator.
diff --git a/docs/narr/MyProject/MyProject.ini b/docs/narr/MyProject/MyProject.ini
index 38cbf879c..6741af913 100644
--- a/docs/narr/MyProject/MyProject.ini
+++ b/docs/narr/MyProject/MyProject.ini
@@ -6,6 +6,7 @@ use = egg:MyProject#app
 reload_templates = true
 debug_authorization = false
 debug_notfound = false
+debug_templates = true
 default_locale_name = en
 
 [server:main]
diff --git a/docs/narr/project.rst b/docs/narr/project.rst
index dfac238b5..97df8a28c 100644
--- a/docs/narr/project.rst
+++ b/docs/narr/project.rst
@@ -233,6 +233,8 @@ section within the ``.ini`` file.  For example, if your application
    reload_templates = true
    debug_authorization = false
    debug_notfound = false
+   debug_templates = true
+   default_locale_name = en
 
 If so, you can use the following command to invoke a debug shell using
 the name ``main`` as a section name:
@@ -279,6 +281,8 @@ following ``.ini`` file content:
    reload_templates = true
    debug_authorization = false
    debug_notfound = false
+   debug_templates = true
+   default_locale_name = en
 
    [pipeline:main]
    pipeline = egg:repoze.tm2#tm
@@ -534,6 +538,17 @@ detected.  See :ref:`reload_templates_section` for more information.
    production applications, as template rendering is slowed when it is
    turned on.
 
+The ``debug_templates`` setting in the ``[app:main]`` section is a
+:mod:`repoze.bfg` -specific setting which is passed into the
+framework.  If it exists, and its value is ``true``, :term:`Chameleon`
+template exceptions will contained more detailed and helpful
+information about the error than when this value is ``false``.  See
+:ref:`debug_templates_section` for more information.
+
+.. warning:: The ``debug_templates`` option should be turned off for
+   production applications, as template rendering is slowed when it is
+   turned on.
+
 Various other settings may exist in this section having to do with
 debugging or influencing runtime behavior of a :mod:`repoze.bfg`
 application.  See :ref:`environment_chapter` for more information
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)
diff --git a/docs/whatsnew-1.3.rst b/docs/whatsnew-1.3.rst
index e8f2ddcdd..32964973d 100644
--- a/docs/whatsnew-1.3.rst
+++ b/docs/whatsnew-1.3.rst
@@ -105,6 +105,16 @@ Minor Feature Additions
   that user-defined decorators can be defined and found during
   :mod:`repoze.bfg` scanning.
 
+- It is now possible to turn on Chameleon template "debugging mode"
+  for all Chameleon BFG templates by setting a BFG-related Paster
+  ``.ini`` file setting named ``debug_templates``. The exceptions
+  raised by Chameleon templates when a rendering fails are sometimes
+  less than helpful.  ``debug_templates`` allows you to configure your
+  application development environment so that exceptions generated by
+  Chameleon during template compilation and execution will contain
+  more helpful debugging information.  This mode is on by default in
+  newly generated projects.  See also :ref:`debug_templates_section`.
+
 Backwards Incompatibilites
 --------------------------
 
diff --git a/repoze/bfg/chameleon_text.py b/repoze/bfg/chameleon_text.py
index deb1cc43d..73457a128 100644
--- a/repoze/bfg/chameleon_text.py
+++ b/repoze/bfg/chameleon_text.py
@@ -51,11 +51,14 @@ class TextTemplateRenderer(object):
     def template(self):
         settings = get_settings()
         auto_reload = settings and settings['reload_templates']
+        debug = settings and settings['debug_templates']
         reg = get_current_registry()
         translate = None
         if reg is not None:
             translate = reg.queryUtility(IChameleonTranslate)
-        return TextTemplateFile(self.path, auto_reload=auto_reload,
+        return TextTemplateFile(self.path,
+                                auto_reload=auto_reload,
+                                debug=debug,
                                 translate=translate)
 
     def implementation(self):
diff --git a/repoze/bfg/chameleon_zpt.py b/repoze/bfg/chameleon_zpt.py
index 687a11305..bacb102bb 100644
--- a/repoze/bfg/chameleon_zpt.py
+++ b/repoze/bfg/chameleon_zpt.py
@@ -34,11 +34,14 @@ class ZPTTemplateRenderer(object):
     def template(self):
         settings = get_settings()
         auto_reload = settings and settings['reload_templates']
+        debug = settings and settings['debug_templates']
         reg = get_current_registry()
         translate = None
         if reg is not None:
             translate = reg.queryUtility(IChameleonTranslate)
-        return PageTemplateFile(self.path, auto_reload=auto_reload,
+        return PageTemplateFile(self.path,
+                                auto_reload=auto_reload,
+                                debug=debug,
                                 translate=translate)
 
     def implementation(self):
diff --git a/repoze/bfg/paster_templates/alchemy/+project+.ini_tmpl b/repoze/bfg/paster_templates/alchemy/+project+.ini_tmpl
index 29fc7e806..1fa0609e0 100644
--- a/repoze/bfg/paster_templates/alchemy/+project+.ini_tmpl
+++ b/repoze/bfg/paster_templates/alchemy/+project+.ini_tmpl
@@ -6,6 +6,7 @@ use = egg:{{project}}#app
 reload_templates = true
 debug_authorization = false
 debug_notfound = false
+debug_templates = true
 default_locale_name = en
 db_string = sqlite:///%(here)s/{{package}}.db
 db_echo = false
diff --git a/repoze/bfg/paster_templates/routesalchemy/+project+.ini_tmpl b/repoze/bfg/paster_templates/routesalchemy/+project+.ini_tmpl
index c249172d3..4f9fd0b00 100644
--- a/repoze/bfg/paster_templates/routesalchemy/+project+.ini_tmpl
+++ b/repoze/bfg/paster_templates/routesalchemy/+project+.ini_tmpl
@@ -6,6 +6,7 @@ use = egg:{{package}}#app
 reload_templates = true
 debug_authorization = false
 debug_notfound = false
+debug_templates = true
 default_locale_name = en
 db_string = sqlite:///%(here)s/{{package}}.db
 
diff --git a/repoze/bfg/paster_templates/starter/+project+.ini_tmpl b/repoze/bfg/paster_templates/starter/+project+.ini_tmpl
index 15be80cf4..9bdeec1ae 100644
--- a/repoze/bfg/paster_templates/starter/+project+.ini_tmpl
+++ b/repoze/bfg/paster_templates/starter/+project+.ini_tmpl
@@ -6,6 +6,7 @@ use = egg:{{project}}#app
 reload_templates = true
 debug_authorization = false
 debug_notfound = false
+debug_templates = true
 default_locale_name = en
 
 [server:main]
diff --git a/repoze/bfg/paster_templates/zodb/+project+.ini_tmpl b/repoze/bfg/paster_templates/zodb/+project+.ini_tmpl
index 51b4e1ab8..993cec596 100644
--- a/repoze/bfg/paster_templates/zodb/+project+.ini_tmpl
+++ b/repoze/bfg/paster_templates/zodb/+project+.ini_tmpl
@@ -6,6 +6,7 @@ use = egg:{{project}}#app
 reload_templates = true
 debug_authorization = false
 debug_notfound = false
+debug_templates = true
 default_locale_name = en
 zodb_uri = file://%(here)s/Data.fs?connection_cache_size=20000