Docs

   - An "Environment and Configuration" chapter was added to the narrative 
     portion of the documentation.

  Features

   - Ensure bfg doesn't generate warnings when running under Python
     2.6.

   - The environment variable ``BFG_RELOAD_TEMPLATES`` is now available
     (serves the same purpose as ``reload_templates`` in the config file).

   - A new configuration file option ``debug_authorization`` was added.
     This turns on printing of security authorization debug statements
     to ``sys.stderr``.  The ``BFG_DEBUG_AUTHORIZATION`` environment
     variable was also added; this performs the same duty.

  Bug Fixes

   - The environment variable ``BFG_SECURITY_DEBUG`` did not always work.
     It has been renamed to ``BFG_DEBUG_AUTHORIZATION`` and fixed.

  Deprecations

   - A deprecation warning is now issued when old API names from the
     ``repoze.bfg.templates`` module are imported.

  Backwards incompatibilities

   - The ``BFG_SECURITY_DEBUG`` environment variable was renamed to
     ``BFG_DEBUG_AUTHORIZATION``.

6 files changed, 119 insertions, 12 deletions

diff --git a/docs/conf.py b/docs/conf.py
index 443a37dd5..92184b267 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -51,9 +51,9 @@ copyright = '2008, Agendaless Consulting'
 # other places throughout the built documents.
 #
 # The short X.Y version.
-version = '0.3.9'
+version = '0.4.0'
 # The full version, including alpha/beta/rc tags.
-release = '0.3.9'
+release = '0.4.0'
 
 # There are two options for replacing |today|: either, you set today to some
 # non-false value, then it is used:
diff --git a/docs/index.rst b/docs/index.rst
index 594add0cb..e89c18494 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -34,6 +34,7 @@ Narrative documentation in chapter form explaining how to use
    narr/models
    narr/security
    narr/events
+   narr/environment
    changes
    glossary
 
diff --git a/docs/narr/environment.rst b/docs/narr/environment.rst
new file mode 100644
index 000000000..9ace43048
--- /dev/null
+++ b/docs/narr/environment.rst
@@ -0,0 +1,60 @@
+.. _environment_chapter:
+
+Environment and Configuration
+=============================
+
+:mod:`repoze.bfg` behavior can be configured through a combination of
+operating system environment variables and ``.ini`` configuration file
+application section settings.  The meaning of the environment
+variables and the configuration file settings overlap.
+
+.. note:: Where a configuration file setting exists with the same
+          meaning as an environment variable, and both are present at
+          application startup time, the environment variable setting
+          takes precedence.
+
+The term "configuration file setting name" refers to a key in the
+``.ini`` configuration for your application.  The configuration file
+setting names documented in this chapter are reserved for
+:mod:`repoze.bfg` use.  You should not use them to indicate
+application-specific configuration settings.
+
++-----------------------------+--------------------------+-------------------------------------+
+| Environment Variable Name   | Config File Setting Name |       Further Information           |
++=============================+==========================+=====================================+
+| ``BFG_RELOAD_TEMPLATES``    |  ``reload_templates``    |  Reload templates without restart   |
+|                             |                          |  when true                          |
+|                             |                          |  See also:                          |
+|                             |                          |  :ref:`reload_templates_section`    |
++-----------------------------+--------------------------+-------------------------------------+
+| ``BFG_DEBUG_AUTHORIZATION`` |  ``debug_authorization`` |  Print authorization failure/success|
+|                             |                          |  messages to stderr when true       |
+|                             |                          |  See also:                          |
+|                             |                          |  :ref:`debug_authorization_section` |
++-----------------------------+--------------------------+-------------------------------------+
+
+Examples
+--------
+
+Let's presume your configuration file is named ``MyProject.ini``, and
+there is a section representing your application named ``[app:main]``
+within the file that represents your :mod:`repoze.bfg` application.
+The configuration file settings documented in the above "Config File
+Setting Name" column would go in the ``[app:main]`` section.  Here's
+an example of such a section::
+
+  [app:main]
+  use = egg:MyProject#app
+  reload_templates = true
+  debug_authorization = true
+
+You can also use environment variables to accomplish the same purpose
+for settings documented as such.  For example, you might start your
+:mod:`repoze.bfg` application using the following command line::
+
+  BFG_DEBUG_AUTHORIZATION=1 BFG_RELOAD_TEMPLATES=1 bin/paster serve MyProject.ini
+
+If you started your application this way, your :mod:`repoze.bfg`
+application would behave in the same manner as if you had placed the
+respective settings in the ``[app:main]`` section of your
+application's ``.ini`` file.
diff --git a/docs/narr/project.rst b/docs/narr/project.rst
index 3bca363e8..751017067 100644
--- a/docs/narr/project.rst
+++ b/docs/narr/project.rst
@@ -300,7 +300,8 @@ your application by requiring more settings in this section.
 The ``reload_templates`` setting in the ``[app:main]`` section is a
 :mod:`repoze.bfg`-specific setting which is passed into the framework.
 If it exists, and is ``true``, :term:`Chameleon` and XSLT template
-changes will not require an application restart to be detected.
+changes will not require an application restart to be detected.  See
+:ref:`reload_templates_section` for more information.
 
 .. warning:: The ``reload_templates`` option should be turned off for
    production applications, as template rendering is slowed when it is
diff --git a/docs/narr/security.rst b/docs/narr/security.rst
index 1053ccc42..b57ad2958 100644
--- a/docs/narr/security.rst
+++ b/docs/narr/security.rst
@@ -164,16 +164,27 @@ be performed.
 See :ref:`location_module` for documentations of functions which use
 location-awareness.
 
-Debugging Security Failures
----------------------------
+.. _debug_authorization_section:
 
-If your application is allowing or denying access inappropriately (in
-your judgment), start your application under a shell using the
-``BFG_SECURITY_DEBUG`` environment variable.  For example::
+Debugging Authorization Failures
+--------------------------------
 
-  $ BFG_SECURITY_DEBUG=1 bin/paster serve myproject.ini
+If your application in your judgment is allowing or denying access
+inappropriately, start your application under a shell using the
+``BFG_DEBUG_AUTHORIZATION`` environment variable set to ``1``.  For
+example::
+
+  $ BFG_DEBUG_AUTHORIZATION=1 bin/paster serve myproject.ini
 
 When any authorization takes place, a message will be logged to the
-console about what ACE in which ACL permitted or denied the
-authorization based on authentication information.
+console (to stderr) about what ACE in which ACL permitted or denied
+the authorization based on authentication information.
+
+This behavior can also be turned on in the application ``.ini`` file
+by setting the ``debug_authorization`` key to ``true`` within the
+application's configuration section, e.g.::
+
+  [app:main]
+  use = egg:MyProject#app
+  debug_authorization = true
 
diff --git a/docs/narr/templates.rst b/docs/narr/templates.rst
index dce66ae3d..4878e728c 100644
--- a/docs/narr/templates.rst
+++ b/docs/narr/templates.rst
@@ -104,6 +104,38 @@ You can also pass XSLT parameters in as keyword arguments:
 This would then assign 'app1' as the value of an ``<xsl:param
 name="param1"/>`` parameter in the XSLT template.
 
+.. _reload_templates_section:
+
+Automatically Reloading Templates
+---------------------------------
+
+It's often convenient to see changes you make to a template file
+appear immediately without needing to restart the application process.
+:mod:`repoze.bfg` allows you configure your application development
+environment so that a change to a template will be automatically
+detected, and the template will be reloaded on the next rendering.
+
+.. warning:: auto-template-reload behavior is not recommended for
+             production sites as it slows rendering; it's usually only
+             desirable during development.
+
+In order to turn on automatic reloading of templates, 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_RELOAD_TEMPLATES`` environment variable set to ``1``,
+For example::
+
+  $ BFG_RELOAD_TEMPLATES=1 bin/paster serve myproject.ini
+
+To use a setting in the the application ``.ini`` file for the same
+purpose, set the ``reload_templates`` key to ``true`` within the
+application's configuration section, e.g.::
+
+  [app:main]
+  use = egg:MyProject#app
+  reload_templates = true
+
 Templating with other Templating Languages
 ------------------------------------------
 
@@ -138,4 +170,6 @@ installed, here's an example of using Mako from within a
    :mod:`repoze.bfg`-style bindings for the `Jinja2
    <http://jinja.pocoo.org/2/documentation>`_ templating system.
 
-
+Note that if you use third-party templating languages, the
+auto-template-reload strategy explained in
+:ref:`reload_templates_section` will not be available.