document the request.settings attribute as well as we can

6 files changed, 46 insertions, 12 deletions

diff --git a/docs/api.rst b/docs/api.rst
index 217a2e289..f8c532cd6 100644
--- a/docs/api.rst
+++ b/docs/api.rst
@@ -20,6 +20,7 @@ documentation is organized alphabetically by module name.
    api/interfaces
    api/location
    api/paster
+   api/registry
    api/renderers
    api/request
    api/response
diff --git a/docs/glossary.rst b/docs/glossary.rst
index 9ba343019..ee7a2784d 100644
--- a/docs/glossary.rst
+++ b/docs/glossary.rst
@@ -826,3 +826,10 @@ Glossary
      :meth:`pyramid.configuration.Configurator.add_view` to make it more
      convenient to register a collection of views as a single class when
      using :term:`url dispatch`.  See also :ref:`handlers_chapter`.
+
+   Deployment settings
+     Deployment settings are settings passed to the :term:`Configurator` as a
+     ``settings`` argument.  These are later accessible via a
+     ``request.registry.settings`` dictionary.  Deployment settings can be
+     used as global application values.
+
diff --git a/docs/latexindex.rst b/docs/latexindex.rst
index f120f1358..4efb193bd 100644
--- a/docs/latexindex.rst
+++ b/docs/latexindex.rst
@@ -94,6 +94,7 @@ API Reference
    api/interfaces
    api/location
    api/paster
+   api/registry
    api/renderers
    api/request
    api/response
diff --git a/docs/narr/startup.rst b/docs/narr/startup.rst
index 9d9baf92d..c57525f4c 100644
--- a/docs/narr/startup.rst
+++ b/docs/narr/startup.rst
@@ -138,7 +138,18 @@ press ``return`` after running ``paster serve development.ini``.
    the application, and the application is running, waiting to receive
    requests.
 
+.. _deployment_settings:
 
+Deployment Settings
+-------------------
+
+Note that an augmented version of the values passed as ``**settings`` to the
+:class:`pyramid.configuration.Configurator` constructor will be available in
+:app:`Pyramid` :term:`view callable` code as ``request.registry.settings``.
+You can create objects you wish to access later from view code, and put them
+into the dictionary you pass to the configurator as ``settings``.  They will
+then be present in the ``request.registry.settings`` dictionary at
+application runtime.
 
 
    
diff --git a/pyramid/configuration.py b/pyramid/configuration.py
index aa436b4d7..844d635a9 100644
--- a/pyramid/configuration.py
+++ b/pyramid/configuration.py
@@ -123,11 +123,10 @@ class Configurator(object):
     is assumed to be the Python package in which the *caller* of the
     ``Configurator`` constructor lives.
 
-    If the ``settings`` argument is passed, it should be a Python
-    dictionary representing the deployment settings for this
-    application.  These are later retrievable using the
-    :meth:`pyramid.registry.Registry.settings` attribute or the
-    :func:`pyramid.settings.get_settings` API.
+    If the ``settings`` argument is passed, it should be a Python dictionary
+    representing the deployment settings for this application.  These are
+    later retrievable using the :attr:`pyramid.registry.Registry.settings`
+    attribute (aka ``request.registry.settings``).
 
     If the ``root_factory`` argument is passed, it should be an object
     representing the default :term:`root factory` for your application
@@ -584,11 +583,11 @@ class Configurator(object):
 
            config.add_settings(external_uri='http://example.com')
 
-        This function is useful when you need to test code that calls
-        the :func:`pyramid.settings.get_settings` API (or the
-        :meth:`pyramid.configuration.Configurator.get_settings`
-        API) and which uses return values from that API.
-
+        This function is useful when you need to test code that calls the
+        :func:`pyramid.settings.get_settings` API (or the
+        :meth:`pyramid.configuration.Configurator.get_settings` API or
+        accesses ``request.settings``) and which uses return values from that
+        API.
         """
         if settings is None:
             settings = {}
@@ -610,8 +609,9 @@ class Configurator(object):
            looked up as attributes of the settings object.
 
         .. note:: the :class:`pyramid.settings.get_settings` and function
-        performs the same duty and the settings attribute can also be
-        accessed as :attr:`pyramid.registry.Registry.settings`"""
+           performs the same duty and the settings attribute can also be
+           accessed as :attr:`pyramid.registry.Registry.settings`
+           """
         return self.registry.settings
 
     def make_wsgi_app(self):
diff --git a/pyramid/registry.py b/pyramid/registry.py
index 226df92db..c772636aa 100644
--- a/pyramid/registry.py
+++ b/pyramid/registry.py
@@ -2,6 +2,20 @@ from zope.component.registry import Components
 from pyramid.interfaces import ISettings
 
 class Registry(Components, dict):
+    """ A registry object is an :term:`application registry`.  The existence
+    of a registry implementation detail of :app:`pyramid`.  It is used by the
+    framework itself to perform mappings of URLs to view callables, as well
+    as servicing other various duties. Despite being an implementation detail
+    of the framework, it has a number of attributes that may be useful within
+    application code.
+
+    For information about the purpose and usage of the application registry,
+    see :ref:`zca_chapter`.
+
+    The application registry is usually accessed as ``request.registry`` in
+    application code.
+
+    """
 
     # for optimization purposes, if no listeners are listening, don't try
     # to notify them