documentation updates

Chris McDonough

2010-07-04 6bc66257ca3abfc02557b94a8086c811797e2ba9

documentation updates

 docs/narr/hooks.rst

@@ -337,6 +337,8 @@
<http://svn.repoze.org/repoze.bfg/trunk/repoze/bfg/traversal.py>`_ of
the :term:`Repoze` Subversion repository.

.. _registering_configuration_decorators:

Registering Configuration Decorators
------------------------------------

@@ -423,3 +425,8 @@

For full details, please read the `Venusian documentation
<http://docs.repoze.org/venusian>`_.

.. note::

   Application-developer-registerable configuration decorators were
   introduced in :mod:`repoze.bfg` 1.3.

 docs/narr/static.rst

@@ -92,6 +92,26 @@
is used as the URL prefix when generating a URL using
:func:`repoze.bfg.url.static_url`.

.. note::

   Using :func:`repoze.bfg.url.static_url` in conjunction with a
   :meth:`repoze.bfg.configuration.Configurator.add_static_view` makes
   it possible to put static media on a separate webserver during
   production (if the ``name`` argument to
   :meth:`repoze.bfg.configuration.Configurator.add_static_view` is a
   URL), while keeping static media package-internal and served by the
   development webserver during development (if the ``name`` argument
   to :meth:`repoze.bfg.configuration.Configurator.add_static_view` is
   a view name).  To create such a circumstance, we suggest using the
   :func:`repoze.bfg.settings.get_settings` API in conjunction with a
   setting in the application ``.ini`` file named ``media_location``.
   Then set the value of ``media_location`` to either a view name or a
   URL depending on whether the application is being run in
   development or in production (use a different `.ini`` file for
   production than you do for development).  This is just a suggestion
   for a pattern; any setting name other than ``media_location`` could
   be used.

For example, the ``static`` ZCML directive may be fed a ``name``
argument which is ``http://example.com/images``:


 docs/whatsnew-1.3.rst

@@ -103,8 +103,8 @@
- Use :term:`Venusian` to perform ``@bfg_view`` decorator scanning
  rather than relying on a BFG-internal decorator scanner.  This means
  that user-defined decorators can be defined and found during
  :mod:`repoze.bfg` scanning (although documentation for doing so is
  currently not provided).
  :mod:`repoze.bfg` scanning.  See
  :ref:`registering_configuration_decorators` for more information.

- It is now possible to turn on Chameleon template "debugging mode"
  for all Chameleon BFG templates by setting a BFG-related Paster
@@ -127,7 +127,7 @@

- Prior to 1.3, a *route predicate* had no access to route pattern
  matching information and had no way to know which route was matched.
  Now, each of the predicate callables fed to the
  As of 1.3a4, each of the predicate callables fed to the
  ``custom_predicates`` argument of
  :meth:`repoze.bfg.configuration.Configurator.add_route` or the
  ``custom_predicates`` ZCML attribute can be a callable accepting two
@@ -202,6 +202,26 @@
- Documentation for the new :ref:`translationdir_directive` and
  :ref:`localenegotiator_directive` ZCML directives were added.

- A section :ref:`custom_route_predicates` was added to the URL
  Dispatch narrative chapter.

- The :ref:`static_resources_section` and
  :ref:`generating_static_resource_urls` sections of the Static
  Resources chapter have been updated to mention using
  :func:`repoze.bfg.url.static_url` to generate URLs to external
  webservers.

- Documentation for registering a new configuration decorator was
  added in :ref:`registering_configuration_decorators`.

- The authorization chapter of the :ref:`bfg_wiki_tutorial` was
  changed to demonstrate authorization via a group rather than via a
  direct username.

- The authorization chapter of the :ref:`bfg_sql_wiki_tutorial` was
  changed to demonstrate authorization via a group rather than via a
  direct username.

Licensing Changes
-----------------


 repoze/bfg/url.py

@@ -95,6 +95,9 @@
    ``request.application_url`` will be used as the prefix (the
    default).

    .. note:: Special treatment of ``_app_url`` was added in
              :mod:`repoze.bfg` 1.3.

    This function raises a :exc:`KeyError` if the URL cannot be
    generated due to missing replacement names.  Extra replacement
    names are ignored.