remove debug_templates untruths related to issue #491

Chris McDonough

2012-03-15 488ea03753d0434b1ddf0c3b2204463c229e7244

remove debug_templates untruths related to issue #491

 docs/narr/project.rst

@@ -497,15 +497,9 @@
template changes will not require an application restart to be detected.  See
:ref:`reload_templates_section` for more information.

The ``pyramid.debug_templates`` setting in the ``[app:main]`` section is a
:app:`Pyramid` -specific setting which is passed into the framework.  If it
exists, and its value is ``true``, :term:`Chameleon` template exceptions will
contain more detailed and helpful information about the error than when this
value is ``false``.  See :ref:`debug_templates_section` for more information.

.. warning:: The ``pyramid.reload_templates`` and ``pyramid.debug_templates``
   options should be turned off for production applications, as template
   rendering is slowed when either is turned on.
.. warning:: The ``pyramid.reload_templates`` option should be turned off for
   production applications, as template rendering is slowed when it is turned
   on.

The ``pyramid.includes`` setting in the ``[app:main]`` section tells Pyramid
to "include" configuration from another package.  In this case, the line

 docs/narr/templates.rst

@@ -593,56 +593,11 @@
.. index::
   pair: debugging; templates

.. _debug_templates_section:
Debugging Templates
-------------------

Nicer Exceptions in Chameleon Templates
---------------------------------------

The exceptions raised by Chameleon templates when a rendering fails
are sometimes less than helpful.  :app:`Pyramid` 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 ``PYRAMID_DEBUG_TEMPLATES`` operating system environment
variable set to ``1``, For example:

.. code-block:: text

  $ PYRAMID_DEBUG_TEMPLATES=1 bin/pserve myproject.ini

To use a setting in the application ``.ini`` file for the same
purpose, set the ``pyramid.debug_templates`` key to ``true`` within
the application's configuration section, e.g.:

.. code-block:: ini
  :linenos:

  [app:main]
  use = egg:MyProject
  pyramid.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:

.. code-block:: text

  File "...", 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:
A :exc:`NameError` exception resulting from rendering a template with an
undefined variable (e.g. ``${wrong}``) might will end like this:

.. code-block:: text

@@ -660,16 +615,8 @@

    NameError: wrong

The latter tells you which template the error occurred in, as well as
The output tells you which template the error occurred in, as well as
displaying the arguments passed to the template itself.

.. note::

   Turning on ``pyramid.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