documentation updates

1 files changed, 20 insertions, 0 deletions

diff --git a/docs/narr/static.rst b/docs/narr/static.rst
index d33831741..b2d481ba5 100644
--- a/docs/narr/static.rst
+++ b/docs/narr/static.rst
@@ -92,6 +92,26 @@ can be served from an external webserver.  In this mode, the ``name``
 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``: