- Add a ``reload_resources`` configuration file setting (aka the

  ``BFG_RELOAD_RESOURCES`` environment variable).  When this is set to
  true, the server never needs to be restarted when moving files
  between directory resource overrides (esp. for templates currently).

- Add a ``reload_all`` configuration file setting (aka the
  ``BFG_RELOAD_ALL`` environment variable) that implies both
  ``reload_resources`` and ``reload_templates``.

- The ``static`` helper view class now uses a ``PackageURLParser`` in
  order to allow for the overriding of static resources (CSS / logo
  files, etc) using the ``resource`` ZCML directive.  The
  ``PackageURLParser`` class was added to a (new) ``static`` module in
  BFG; it is a subclass of the ``StaticURLParser`` class in
  ``paste.urlparser``.

- The ``repoze.bfg.templating.renderer_from_cache`` function now
  checks for the ``reload_resources`` setting; if it's true, it does
  not register a template renderer (it won't use the registry as a
  template renderer cache).

- Add ``pkg_resources`` to the glossary.

- Update the "Environment" docs to note the existence of
  ``reload_resources`` and ``reload_all``.

- Use a colon instead of a tab as the separator between package name
  and relpath to form the "spec" when register a ITemplateRenderer.

3 files changed, 61 insertions, 2 deletions

diff --git a/docs/glossary.rst b/docs/glossary.rst
index 303c20703..3abe31ea6 100644
--- a/docs/glossary.rst
+++ b/docs/glossary.rst
@@ -17,6 +17,13 @@ Glossary
     `Setuptools <http://peak.telecommunity.com/DevCenter/setuptools>`_
     builds on Python's ``distutils`` to provide easier building,
     distribution, and installation of libraries and applications.
+  pkg_resources
+    A module which ships with :term:`setuptools` that provides an API
+    for addressing "resource files" within Python packages.  Resource
+    files are static files, template files, etc; basically anything
+    non-Python-source that lives in a Python package can be considered
+    a resource file.  See also `PkgResources
+    <http://peak.telecommunity.com/DevCenter/PkgResources>`_
   Package
     A directory on disk which contains an ``__init__.py`` file, making
     it recognizable to Python as a location which can be ``import`` -ed.
diff --git a/docs/narr/environment.rst b/docs/narr/environment.rst
index 6df4157e2..45b544df5 100644
--- a/docs/narr/environment.rst
+++ b/docs/narr/environment.rst
@@ -27,6 +27,11 @@ application-specific configuration settings.
 |                                 |                             |  See also:                             |
 |                                 |                             |  :ref:`reload_templates_section`       |
 +---------------------------------+-----------------------------+----------------------------------------+
+| ``BFG_RELOAD_RESOURCES``        |  ``reload_resources``       |  Don't cache any resource file data    |
+|                                 |                             |  when true                             |
+|                                 |                             |  See also:                             |
+|                                 |                             |  :ref:`overriding_resources_section`   |
++---------------------------------+-----------------------------+----------------------------------------+
 | ``BFG_DEBUG_AUTHORIZATION``     |  ``debug_authorization``    |  Print view authorization failure &    |
 |                                 |                             |  success info to stderr when true      |
 |                                 |                             |  See also:                             |
@@ -39,6 +44,8 @@ application-specific configuration settings.
 +---------------------------------+-----------------------------+----------------------------------------+
 | ``BFG_DEBUG_ALL``               |  ``debug_all``              |  Turns all debug_* settings on.        |
 +---------------------------------+-----------------------------+----------------------------------------+
+| ``BFG_RELOAD_ALL``              |  ``reload_all``             |  Turns all reload_* settings on.       |
++---------------------------------+-----------------------------+----------------------------------------+
 
 Examples
 --------
@@ -66,9 +73,52 @@ 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.
 
-If you want to turn all ``debug`` settings (every debug setting that
-starts with ``debug_``). on in one fell swoop, you can use
+If you want to turn all ``debug`` settings (every setting that starts
+with ``debug_``). on in one fell swoop, you can use
 ``BFG_DEBUG_ALL=1`` as an environment variable setting or you may use
 ``debug_all=true`` in the config file.  Note that this does not effect
 settings that do not start with ``debug_*`` such as
 ``reload_templates``.
+
+If you want to turn all ``reload`` settings (everysetting that starts
+with ``reload_``). on in one fell swoop, you can use
+``BFG_RELOAD_ALL=1`` as an environment variable setting or you may use
+``reload_all=true`` in the config file.  Note that this does not
+effect settings that do not start with ``reload_*`` such as
+``debug_notfound``.
+
+Understanding the Distinction Between ``reload_templates`` and ``reload_resources``
+-----------------------------------------------------------------------------------
+
+The difference between ``reload_resources`` and ``reload_templates``
+is a bit subtle.  Templates are themselves also treated by
+:mod:`repoze.bfg` as :term:`pkg_resources` resource files (along with
+static files and other resources), so the distinction can be
+confusing.  It's helpful to read :ref:`overriding_resources_section`
+for some context about resources in general.
+
+When ``reload_templates`` is true, :mod:`repoze.bfg`` takes advantage
+of the underlying templating systems' ability to check for file
+modifications to an individual template file.  When
+``reload_templates`` is true but ``reload_resources`` is *not* true,
+the template filename returned by pkg_resources is cached by
+:mod:`repoze.bfg` on the first request.  Subsequent requests for the
+same template file will return a cached template filename.  The
+underlying templating system checks for modifications to this
+particular file for every request.  Setting ``reload_templates`` to
+``True`` doesn't effect performance dramatically (although it should
+still not be used in production because it has some effect).
+
+However, when ``reload_resources`` is true, :mod:`repoze.bfg` will not
+cache the template filename, meaning you can see the effect of
+changing the content of an overridden resource directory for templates
+without restarting the server after every change.  Subsequent requests
+for the same template file may return different filenames based on the
+current state of overridden resource directories. Setting
+``reload_resources`` to ``True`` effects performance *dramatically*
+(slowing things down by an order of magnitude for each template
+rendering) but it's convenient when moving files around in overridden
+resource directories. ``reload_resources`` makes the system *very
+slow* when templates are in use.  Never set ``reload_resources`` to
+``True`` on a production system.
+
diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst
index 85b1131bb..9eba8a92c 100644
--- a/docs/narr/hooks.rst
+++ b/docs/narr/hooks.rst
@@ -118,6 +118,8 @@ an object that implements any particular interface; it simply needs
 have a ``status`` attribute, a ``headerlist`` attribute, and and
 ``app_iter`` attribute.
 
+.. _overriding_resources_section:
+
 Overriding Resources
 --------------------