review and fix configurator docs in random places

7 files changed, 80 insertions, 75 deletions

diff --git a/docs/api/config.rst b/docs/api/config.rst
index d744418b3..a8c193b60 100644
--- a/docs/api/config.rst
+++ b/docs/api/config.rst
@@ -5,7 +5,7 @@
 
 .. automodule:: pyramid.config
 
-  .. autoclass:: Configurator(registry=None, package=None, settings=None, root_factory=None, authentication_policy=None, authorization_policy=None, renderers=DEFAULT_RENDERERS, debug_logger=None, locale_negotiator=None, request_factory=None, renderer_globals_factory=None, default_permission=None, session_factory=None, autocommit=False)
+  .. autoclass:: Configurator
 
      .. attribute:: registry
 
@@ -36,9 +36,9 @@
 
      .. automethod:: absolute_asset_spec
 
-     .. automethod:: setup_registry(settings=None, root_factory=None, authentication_policy=None, renderers=DEFAULT_RENDERERS, debug_logger=None, locale_negotiator=None, request_factory=None, renderer_globals_factory=None)
+     .. automethod:: setup_registry
 
-     .. automethod:: add_renderer(name, factory)
+     .. automethod:: add_renderer
 
      .. automethod:: add_response_adapter
 
@@ -64,10 +64,6 @@
 
      .. automethod:: scan
 
-     .. automethod:: set_forbidden_view
-
-     .. automethod:: set_notfound_view
-
      .. automethod:: set_locale_negotiator
 
      .. automethod:: set_default_permission
@@ -78,8 +74,6 @@
 
      .. automethod:: set_root_factory
 
-     .. automethod:: set_renderer_globals_factory(factory)
-
      .. automethod:: set_view_mapper
 
      .. automethod:: set_authentication_policy
@@ -94,6 +88,13 @@
 
      .. automethod:: testing_add_renderer
 
+     .. automethod:: set_forbidden_view
+
+     .. automethod:: set_notfound_view
+
+     .. automethod:: set_renderer_globals_factory(factory)
+
+
   .. attribute:: global_registries
 
      The set of registries that have been created for :app:`Pyramid`
diff --git a/pyramid/config/__init__.py b/pyramid/config/__init__.py
index 91c351fa5..c7ee8c47f 100644
--- a/pyramid/config/__init__.py
+++ b/pyramid/config/__init__.py
@@ -71,48 +71,46 @@ class Configurator(
     ``authorization_policy``, ``renderers``, ``debug_logger``,
     ``locale_negotiator``, ``request_factory``, ``renderer_globals_factory``,
     ``default_permission``, ``session_factory``, ``default_view_mapper``,
-    ``autocommit``, and ``exceptionresponse_view``.
-
-    If the ``registry`` argument is passed as a non-``None`` value, it
-    must be an instance of the :class:`pyramid.registry.Registry`
-    class representing the registry to configure.  If ``registry`` is
-    ``None``, the configurator will create a
-    :class:`pyramid.registry.Registry` instance itself; it will
-    also perform some default configuration that would not otherwise
-    be done.  After construction, the configurator may be used to add
-    configuration to the registry.  The overall state of a registry is
-    called the 'configuration state'.
+    ``autocommit``, ``exceptionresponse_view`` and ``route_prefix``.
+
+    If the ``registry`` argument is passed as a non-``None`` value, it must
+    be an instance of the :class:`pyramid.registry.Registry` class
+    representing the registry to configure.  If ``registry`` is ``None``, the
+    configurator will create a :class:`pyramid.registry.Registry` instance
+    itself; it will also perform some default configuration that would not
+    otherwise be done.  After its construction, the configurator may be used
+    to add further configuration to the registry.
 
     .. warning:: If a ``registry`` is passed to the Configurator
        constructor, all other constructor arguments except ``package``
        are ignored.
 
-    If the ``package`` argument is passed, it must be a reference to a
-    Python :term:`package` (e.g. ``sys.modules['thepackage']``) or a
-    :term:`dotted Python name` to same.  This value is used as a basis
-    to convert relative paths passed to various configuration methods,
-    such as methods which accept a ``renderer`` argument, into
-    absolute paths.  If ``None`` is passed (the default), the package
-    is assumed to be the Python package in which the *caller* of the
-    ``Configurator`` constructor lives.
+    If the ``package`` argument is passed, it must be a reference to a Python
+    :term:`package` (e.g. ``sys.modules['thepackage']``) or a :term:`dotted
+    Python name` to the same.  This value is used as a basis to convert
+    relative paths passed to various configuration methods, such as methods
+    which accept a ``renderer`` argument, into absolute paths.  If ``None``
+    is passed (the default), the package 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 :attr:`pyramid.registry.Registry.settings`
-    attribute (aka ``request.registry.settings``).
+    representing the :term:`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
-    or a :term:`dotted Python name` to same.  If it is ``None``, a
-    default root factory will be used.
+    representing the default :term:`root factory` for your application or a
+    :term:`dotted Python name` to the same.  If it is ``None``, a default
+    root factory will be used.
 
     If ``authentication_policy`` is passed, it should be an instance
     of an :term:`authentication policy` or a :term:`dotted Python
-    name` to same.
+    name` to the same.
 
     If ``authorization_policy`` is passed, it should be an instance of
     an :term:`authorization policy` or a :term:`dotted Python name` to
-    same.
+    the same.
 
     .. note:: A ``ConfigurationError`` will be raised when an
        authorization policy is supplied without also supplying an
@@ -137,14 +135,14 @@ class Configurator(
     same.  See :ref:`custom_locale_negotiator`.
 
     If ``request_factory`` is passed, it should be a :term:`request
-    factory` implementation or a :term:`dotted Python name` to same.
+    factory` implementation or a :term:`dotted Python name` to the same.
     See :ref:`changing_the_request_factory`.  By default it is ``None``,
     which means use the default request factory.
 
     If ``renderer_globals_factory`` is passed, it should be a :term:`renderer
-    globals` factory implementation or a :term:`dotted Python name` to same.
-    See :ref:`adding_renderer_globals`.  By default, it is ``None``, which
-    means use no renderer globals factory.
+    globals` factory implementation or a :term:`dotted Python name` to the
+    same.  See :ref:`adding_renderer_globals`.  By default, it is ``None``,
+    which means use no renderer globals factory.
 
     .. warning:: as of Pyramid 1.1, ``renderer_globals_factory`` is
        deprecated.  Instead, use a BeforeRender event subscriber as per
@@ -266,16 +264,15 @@ class Configurator(
                        session_factory=None, default_view_mapper=None,
                        exceptionresponse_view=default_exceptionresponse_view):
         """ When you pass a non-``None`` ``registry`` argument to the
-        :term:`Configurator` constructor, no initial 'setup' is performed
+        :term:`Configurator` constructor, no initial setup is performed
         against the registry.  This is because the registry you pass in may
         have already been initialized for use under :app:`Pyramid` via a
         different configurator.  However, in some circumstances (such as when
-        you want to use the Zope 'global` registry instead of a registry
-        created as a result of the Configurator constructor), or when you
-        want to reset the initial setup of a registry, you *do* want to
-        explicitly initialize the registry associated with a Configurator for
-        use under :app:`Pyramid`.  Use ``setup_registry`` to do this
-        initialization.
+        you want to use a global registry instead of a registry created as a
+        result of the Configurator constructor), or when you want to reset
+        the initial setup of a registry, you *do* want to explicitly
+        initialize the registry associated with a Configurator for use under
+        :app:`Pyramid`.  Use ``setup_registry`` to do this initialization.
 
         ``setup_registry`` configures settings, a root factory, security
         policies, renderers, a debug logger, a locale negotiator, and various
@@ -421,7 +418,7 @@ class Configurator(
 
     def action(self, discriminator, callable=None, args=(), kw=None, order=0):
         """ Register an action which will be executed when
-        :meth:`pyramid.config.Configuration.commit` is called (or executed
+        :meth:`pyramid.config.Configurator.commit` is called (or executed
         immediately if ``autocommit`` is ``True``).
 
         .. warning:: This method is typically only used by :app:`Pyramid`
@@ -471,7 +468,7 @@ class Configurator(
 
     def commit(self):
         """ Commit any pending configuration actions. If a configuration
-        conflict is detected in the pending configuration actins, this method
+        conflict is detected in the pending configuration actions, this method
         will raise a :exc:`ConfigurationConflictError`; within the traceback
         of this error will be information about the source of the conflict,
         usually including file names and line numbers of the cause of the
diff --git a/pyramid/config/factories.py b/pyramid/config/factories.py
index cc73d596c..1421082cd 100644
--- a/pyramid/config/factories.py
+++ b/pyramid/config/factories.py
@@ -12,7 +12,12 @@ class FactoriesConfiguratorMixin(object):
     def set_root_factory(self, factory):
         """ Add a :term:`root factory` to the current configuration
         state.  If the ``factory`` argument is ``None`` a default root
-        factory will be registered."""
+        factory will be registered.
+
+        .. note:: Using the ``root_factory`` argument to the
+           :class:`pyramid.config.Configurator` constructor
+           can be used to achieve the same purpose.
+        """
         factory = self.maybe_dotted(factory)
         if factory is None:
             factory = DefaultRootFactory
diff --git a/pyramid/config/security.py b/pyramid/config/security.py
index 4a4b7a1ad..897d4bbec 100644
--- a/pyramid/config/security.py
+++ b/pyramid/config/security.py
@@ -2,7 +2,6 @@ from pyramid.interfaces import IAuthorizationPolicy
 from pyramid.interfaces import IAuthenticationPolicy
 from pyramid.interfaces import IDefaultPermission
 
-from pyramid.authorization import ACLAuthorizationPolicy
 from pyramid.exceptions import ConfigurationError
 from pyramid.config.util import action_method
 
@@ -13,6 +12,11 @@ class SecurityConfiguratorMixin(object):
         current configuration.  The ``policy`` argument must be an instance
         of an authentication policy or a :term:`dotted Python name`
         that points at an instance of an authentication policy.
+
+        .. note:: Using the ``authentication_policy`` argument to the
+           :class:`pyramid.config.Configurator` constructor
+           can be used to achieve the same purpose.
+        
         """
         self._set_authentication_policy(policy)
         def ensure():
@@ -36,6 +40,10 @@ class SecurityConfiguratorMixin(object):
         current configuration.  The ``policy`` argument must be an instance
         of an authorization policy or a :term:`dotted Python name` that points
         at an instance of an authorization policy.
+
+        .. note:: Using the ``authorization_policy`` argument to the
+           :class:`pyramid.config.Configurator` constructor
+           can be used to achieve the same purpose.
         """
         self._set_authorization_policy(policy)
         def ensure():
@@ -76,12 +84,11 @@ class SecurityConfiguratorMixin(object):
 
           If a default permission is in effect, view configurations meant to
           create a truly anonymously accessible view (even :term:`exception
-          view` views) *must* use the explicit permission string
-          :data:`pyramid.security.NO_PERMISSION_REQUIRED` as the permission.
-          When this string is used as the ``permission`` for a view
-          configuration, the default permission is ignored, and the view is
-          registered, making it available to all callers regardless of their
-          credentials.
+          view` views) *must* use the value of the permission importable as
+          :data:`pyramid.security.NO_PERMISSION_REQUIRED`.  When this string
+          is used as the ``permission`` for a view configuration, the default
+          permission is ignored, and the view is registered, making it
+          available to all callers regardless of their credentials.
 
         See also :ref:`setting_a_default_permission`.
 
diff --git a/pyramid/config/settings.py b/pyramid/config/settings.py
index 513a57871..fad442853 100644
--- a/pyramid/config/settings.py
+++ b/pyramid/config/settings.py
@@ -9,11 +9,8 @@ class SettingsConfiguratorMixin(object):
         return settings
 
     def add_settings(self, settings=None, **kw):
-        """Augment the ``settings`` argument passed in to the Configurator
-        constructor with one or more 'setting' key/value pairs.  A setting is
-        a single key/value pair in the dictionary-ish object returned from
-        the API :attr:`pyramid.registry.Registry.settings` and
-        :meth:`pyramid.config.Configurator.get_settings`.
+        """Augment the :term:`deployment settings` with one or more
+        key/value pairs. 
 
         You may pass a dictionary::
 
@@ -42,11 +39,7 @@ class SettingsConfiguratorMixin(object):
         application.  A deployment settings object is a dictionary-like
         object that contains key/value pairs based on the dictionary passed
         as the ``settings`` argument to the
-        :class:`pyramid.config.Configurator` constructor or the
-        :func:`pyramid.router.make_app` API.
-
-        .. note:: For backwards compatibility, dictionary keys can also be
-           looked up as attributes of the settings object.
+        :class:`pyramid.config.Configurator` constructor.
 
         .. note:: the :attr:`pyramid.registry.Registry.settings` API
            performs the same duty.
diff --git a/pyramid/config/tweens.py b/pyramid/config/tweens.py
index 4551c7fac..83067f0fe 100644
--- a/pyramid/config/tweens.py
+++ b/pyramid/config/tweens.py
@@ -11,6 +11,8 @@ class TweensConfiguratorMixin(object):
     @action_method
     def add_tween(self, tween_factory, alias=None, under=None, over=None):
         """
+        .. note:: This feature is new as of Pyramid 1.2.
+
         Add a 'tween factory'.  A :term:`tween` (a contraction of 'between')
         is a bit of code that sits between the Pyramid router's main request
         handling function and the upstream WSGI component that uses
@@ -98,7 +100,6 @@ class TweensConfiguratorMixin(object):
 
         For more information, see :ref:`registering_tweens`.
 
-        .. note:: This feature is new as of Pyramid 1.2.
         """
         return self._add_tween(tween_factory, alias=alias, under=under,
                                over=over, explicit=False)
diff --git a/pyramid/config/views.py b/pyramid/config/views.py
index 5ec2f68a1..c4c9f1fbc 100644
--- a/pyramid/config/views.py
+++ b/pyramid/config/views.py
@@ -1249,14 +1249,15 @@ class ViewsConfiguratorMixin(object):
 
         The ``mapper`` should argument be an object implementing
         :class:`pyramid.interfaces.IViewMapperFactory` or a :term:`dotted
-        Python name` to such an object.
+        Python name` to such an object.  The provided ``mapper`` will become
+        the default view mapper to be used by all subsequent :term:`view
+        configuration` registrations.
 
-        The provided ``mapper`` will become the default view mapper to be
-        used by all subsequent :term:`view configuration` registrations, as
-        if you had passed a ``default_view_mapper`` argument to the
-        :class:`pyramid.config.Configurator` constructor.
-        
         See also :ref:`using_a_view_mapper`.
+
+        .. note:: Using the ``default_view_mapper`` argument to the
+           :class:`pyramid.config.Configurator` constructor
+           can be used to achieve the same purpose.
         """
         mapper = self.maybe_dotted(mapper)
         self.registry.registerUtility(mapper, IViewMapperFactory)
@@ -1293,7 +1294,7 @@ class ViewsConfiguratorMixin(object):
         be performed against the default root factory ACL.
 
         Any other keyword arguments sent to ``add_static_view`` are passed on
-        to :meth:`pyramid.config.Configuration.add_route` (e.g. ``factory``,
+        to :meth:`pyramid.config.Configurator.add_route` (e.g. ``factory``,
         perhaps to define a custom factory with a custom ACL for this static
         view).