Merge pull request #815 from tshepang/temp

some pyramid.config API documentation improvements

8 files changed, 77 insertions, 88 deletions

diff --git a/docs/api/config.rst b/docs/api/config.rst
index e6a67830e..39d504348 100644
--- a/docs/api/config.rst
+++ b/docs/api/config.rst
@@ -108,9 +108,7 @@
         :class:`pyramid.registry.Introspectable` class (used during
         directives to provide introspection to actions).
 
-        .. note::
-
-           This attribute is new as of :app:`Pyramid` 1.3.
+        .. versionadded:: 1.3
 
      .. attribute:: introspector
 
@@ -118,9 +116,7 @@
         instance implementing the :class:`pyramid.interfaces.IIntrospector`
         interface.
 
-        .. note::
-
-           This attribute is new as of :app:`Pyramid` 1.3.
+        .. versionadded:: 1.3
 
      .. attribute:: registry
 
diff --git a/pyramid/config/__init__.py b/pyramid/config/__init__.py
index 90bd89116..d662c7d3a 100644
--- a/pyramid/config/__init__.py
+++ b/pyramid/config/__init__.py
@@ -104,14 +104,7 @@ class Configurator(
     A Configurator is used to configure a :app:`Pyramid`
     :term:`application registry`.
 
-    The Configurator accepts a number of arguments: ``registry``,
-    ``package``, ``settings``, ``root_factory``, ``authentication_policy``,
-    ``authorization_policy``, ``renderers``, ``debug_logger``,
-    ``locale_negotiator``, ``request_factory``, ``renderer_globals_factory``,
-    ``default_permission``, ``session_factory``, ``default_view_mapper``,
-    ``autocommit``, ``exceptionresponse_view`` and ``route_prefix``.
-
-    If the ``registry`` argument is passed as a non-``None`` value, it must
+    If the ``registry`` argument is not ``None``, 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
@@ -119,9 +112,9 @@ class Configurator(
     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.
+    .. warning:: If ``registry`` is assigned the above-mentioned class
+       instance, all other constructor arguments are ignored,
+       with the exception of ``package``.
 
     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
@@ -154,12 +147,12 @@ class Configurator(
        authorization policy is supplied without also supplying an
        authentication policy (authorization requires authentication).
 
-    If ``renderers`` is passed, it should be a list of tuples
-    representing a set of :term:`renderer` factories which should be
-    configured into this application (each tuple representing a set of
+    If ``renderers`` is ``None`` (the default), a default set of
+    :term:`renderer` factories is used. Else, it should be a list of
+    tuples representing a set of renderer factories which should be
+    configured into this application, and each tuple representing a set of
     positional values that should be passed to
-    :meth:`pyramid.config.Configurator.add_renderer`).  If
-    it is not passed, a default set of renderer factories is used.
+    :meth:`pyramid.config.Configurator.add_renderer`.
 
     If ``debug_logger`` is not passed, a default debug logger that logs to a
     logger will be used (the logger name will be the package name of the
@@ -182,10 +175,9 @@ class Configurator(
     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 :ref:`beforerender_event`.
+    .. deprecated:: 1.1
+       Use a BeforeRender event subscriber as per :ref:`beforerender_event`
+       in place of ``renderer_globals_factory``.
 
     If ``default_permission`` is passed, it should be a
     :term:`permission` string to be used as the default permission for
@@ -218,15 +210,15 @@ class Configurator(
     :meth:`pyramid.config.Configurator.commit` is called.  When
     :meth:`pyramid.config.Configurator.commit` is called, the actions implied
     by the called methods will be checked for configuration conflicts unless
-    ``autocommit`` is ``True``.  If a conflict is detected a
+    ``autocommit`` is ``True``.  If a conflict is detected, a
     ``ConfigurationConflictError`` will be raised.  Calling
     :meth:`pyramid.config.Configurator.make_wsgi_app` always implies a final
     commit.
 
     If ``default_view_mapper`` is passed, it will be used as the default
     :term:`view mapper` factory for view configurations that don't otherwise
-    specify one (see :class:`pyramid.interfaces.IViewMapperFactory`).  If a
-    default_view_mapper is not passed, a superdefault view mapper will be
+    specify one (see :class:`pyramid.interfaces.IViewMapperFactory`).  If
+    ``default_view_mapper`` is not passed, a superdefault view mapper will be
     used.
 
     If ``exceptionresponse_view`` is passed, it must be a :term:`view
@@ -236,18 +228,26 @@ class Configurator(
     be registered, and all raised exception responses will be bubbled up to
     Pyramid's caller.  By
     default, the ``pyramid.httpexceptions.default_exceptionresponse_view``
-    function is used as the ``exceptionresponse_view``.  This argument is new
-    in Pyramid 1.1.
+    function is used as the ``exceptionresponse_view``.
 
     If ``route_prefix`` is passed, all routes added with
     :meth:`pyramid.config.Configurator.add_route` will have the specified path
-    prepended to their pattern. This parameter is new in Pyramid 1.2.
+    prepended to their pattern.
 
     If ``introspection`` is passed, it must be a boolean value.  If it's
     ``True``, introspection values during actions will be kept for use
     for tools like the debug toolbar.  If it's ``False``, introspection
     values provided by registrations will be ignored.  By default, it is
-    ``True``.  This parameter is new as of Pyramid 1.3.
+    ``True``.
+
+    .. versionadded:: 1.1
+       The ``exceptionresponse_view`` argument.
+
+    .. versionadded:: 1.2
+       The ``route_prefix`` argument.
+
+    .. versionadded:: 1.3
+       The ``introspection`` argument.
     """
     manager = manager # for testing injection
     venusian = venusian # for testing injection
@@ -721,7 +721,9 @@ class Configurator(
         because the ``route_prefix`` argument will be prepended to the
         pattern.
 
-        The ``route_prefix`` parameter is new as of Pyramid 1.2.
+        .. versionadded:: 1.2
+           The ``route_prefix`` parameter.
+
         """
         # """ <-- emacs
 
@@ -919,8 +921,6 @@ class Configurator(
         and scanned.  See the :term:`Venusian` documentation for more
         information about the ``ignore`` argument.
 
-        .. note:: the ``ignore`` argument is new in Pyramid 1.3.
-        
         To perform a ``scan``, Pyramid creates a Venusian ``Scanner`` object.
         The ``kw`` argument represents a set of keyword arguments to pass to
         the Venusian ``Scanner`` object's constructor.  See the
@@ -932,7 +932,12 @@ class Configurator(
         may require additional arguments.  Providing this argument is not
         often necessary; it's an advanced usage.
 
-        .. note:: the ``**kw`` argument is new in Pyramid 1.1
+        .. versionadded:: 1.1
+           The ``**kw`` argument.
+
+        .. versionadded:: 1.3
+           The ``ignore`` argument.
+
         """
         package = self.maybe_dotted(package)
         if package is None: # pragma: no cover
diff --git a/pyramid/config/adapters.py b/pyramid/config/adapters.py
index dad60660a..3ce0680af 100644
--- a/pyramid/config/adapters.py
+++ b/pyramid/config/adapters.py
@@ -38,9 +38,8 @@ class AdaptersConfiguratorMixin(object):
         :meth:`pyramid.config.Configurator.add_subscriber_predicate` before it
         can be used.  See :ref:`subscriber_predicates` for more information.
 
-        .. note::
-
-           THe ``**predicates`` argument is new as of Pyramid 1.4.
+        .. versionadded:: 1.4
+           The ``**predicates`` argument.
         """
         dotted = self.maybe_dotted
         subscriber, iface = dotted(subscriber), dotted(iface)
@@ -274,6 +273,8 @@ class AdaptersConfiguratorMixin(object):
     @action_method
     def add_resource_url_adapter(self, adapter, resource_iface=None):
         """
+        .. versionadded:: 1.3
+
         When you add a traverser as described in
         :ref:`changing_the_traverser`, it's convenient to continue to use the
         :meth:`pyramid.request.Request.resource_url` API.  However, since the
@@ -299,10 +300,6 @@ class AdaptersConfiguratorMixin(object):
         ``None``, the url adapter will be used for every type of resource.
 
         See :ref:`changing_resource_url` for more information.
-
-        .. note::
-
-           This API is new in Pyramid 1.3.
         """
         adapter = self.maybe_dotted(adapter)
         resource_iface = self.maybe_dotted(resource_iface)
diff --git a/pyramid/config/rendering.py b/pyramid/config/rendering.py
index 4f33b23d9..356bf033e 100644
--- a/pyramid/config/rendering.py
+++ b/pyramid/config/rendering.py
@@ -73,11 +73,9 @@ class RenderingConfiguratorMixin(object):
         dictionary, and therefore will be made available to the code
         which uses the renderer.
 
-        .. warning::
-
-           This method is deprecated as of Pyramid 1.1.  Use a BeforeRender
-           event subscriber as documented in the :ref:`hooks_chapter` chapter
-           instead.
+        .. deprecated:: 1.1
+           Use a BeforeRender event subscriber as documented in the
+           :ref:`hooks_chapter` chapter instead.
 
         .. note::
 
diff --git a/pyramid/config/routes.py b/pyramid/config/routes.py
index e06d0fecd..7a7bbae1a 100644
--- a/pyramid/config/routes.py
+++ b/pyramid/config/routes.py
@@ -142,7 +142,7 @@ class RoutesConfiguratorMixin(object):
           request; it will only be useful for URL generation.  By default,
           ``static`` is ``False``.  See :ref:`static_route_narr`.
 
-          .. note:: New in :app:`Pyramid` 1.1.
+          .. versionadded:: 1.1
 
         Predicate Arguments
 
@@ -180,9 +180,9 @@ class RoutesConfiguratorMixin(object):
           will match if the request has *any* request method.  If this
           predicate returns ``False``, route matching continues.
 
-          .. note:: The ability to pass a tuple of items as
-                   ``request_method`` is new as of Pyramid 1.2.  Previous
-                   versions allowed only a string.
+          .. versionchanged:: 1.2
+             The ability to pass a tuple of items as ``request_method``.
+             Previous versions allowed only a string.
 
         path_info
 
@@ -276,8 +276,10 @@ class RoutesConfiguratorMixin(object):
           :meth:`pyramid.config.Configurator.add_view_predicate`.  More than
           one key/value pair can be used at the same time.  See
           :ref:`view_and_route_predicates` for more information about
-          third-party predicates.  This argument is new as of Pyramid 1.4.
-          
+          third-party predicates.
+
+          .. versionadded:: 1.4
+
         View-Related Arguments
 
         .. warning::
@@ -291,7 +293,7 @@ class RoutesConfiguratorMixin(object):
 
         view
 
-          .. warning:: Deprecated as of :app:`Pyramid` 1.1.
+          .. deprecated:: 1.1
 
           A Python object or :term:`dotted Python name` to the same
           object that will be used as a view callable when this route
@@ -299,7 +301,7 @@ class RoutesConfiguratorMixin(object):
 
         view_context
 
-          .. warning:: Deprecated as of :app:`Pyramid` 1.1.
+          .. deprecated:: 1.1
 
           A class or an :term:`interface` or :term:`dotted Python
           name` to the same object which the :term:`context` of the
@@ -315,7 +317,7 @@ class RoutesConfiguratorMixin(object):
 
         view_permission
 
-          .. warning:: Deprecated as of :app:`Pyramid` 1.1.
+          .. deprecated:: 1.1
 
           The permission name required to invoke the view associated
           with this route.  e.g. ``edit``. (see
@@ -329,7 +331,7 @@ class RoutesConfiguratorMixin(object):
 
         view_renderer
 
-          .. warning:: Deprecated as of :app:`Pyramid` 1.1.
+          .. deprecated:: 1.1
 
           This is either a single string term (e.g. ``json``) or a
           string implying a path or :term:`asset specification`
@@ -353,7 +355,7 @@ class RoutesConfiguratorMixin(object):
 
         view_attr
 
-          .. warning:: Deprecated as of :app:`Pyramid` 1.1.
+          .. deprecated:: 1.1
 
           The view machinery defaults to using the ``__call__`` method
           of the view callable (or the function itself, if the view
@@ -491,9 +493,7 @@ class RoutesConfiguratorMixin(object):
 
         See :ref:`view_and_route_predicates` for more information.
 
-        .. note::
-
-           This method is new as of Pyramid 1.4.
+        .. versionadded:: 1.4
         """
         self._add_predicate(
             'route',
diff --git a/pyramid/config/testing.py b/pyramid/config/testing.py
index 7141a5049..2ab85b1f5 100644
--- a/pyramid/config/testing.py
+++ b/pyramid/config/testing.py
@@ -37,19 +37,11 @@ class TestingConfiguratorMixin(object):
         not provided (or it is provided, and is ``None``), the default value
         ``[]`` (the empty list) will be returned by ``remember``.
 
-        .. note::
-
-           ``remember_result`` is new as of Pyramid 1.4.
-
         ``forget_result``, if provided, should be the result returned by
         the ``forget`` method of the faux authentication policy.  If it is
         not provided (or it is provided, and is ``None``), the default value
         ``[]`` (the empty list) will be returned by ``forget``.
 
-        .. note::
-
-           ``forget_result`` is new as of Pyramid 1.4.
-
         The behavior of the registered :term:`authentication policy`
         depends on the values provided for the ``userid`` and
         ``groupids`` argument.  The authentication policy will return
@@ -64,6 +56,12 @@ class TestingConfiguratorMixin(object):
         :func:`pyramid.security.authenticated_userid`,
         :func:`pyramid.security.effective_principals`, and
         :func:`pyramid.security.principals_allowed_by_permission`.
+
+        .. versionadded:: 1.4
+           The ``remember_result`` argument.
+
+        .. versionadded:: 1.4
+           The ``forget_result`` argument.
         """
         from pyramid.testing import DummySecurityPolicy
         policy = DummySecurityPolicy(
diff --git a/pyramid/config/tweens.py b/pyramid/config/tweens.py
index 1bc6dc95c..cd14c9ff6 100644
--- a/pyramid/config/tweens.py
+++ b/pyramid/config/tweens.py
@@ -24,7 +24,7 @@ from pyramid.config.util import (
 class TweensConfiguratorMixin(object):
     def add_tween(self, tween_factory, under=None, over=None):
         """
-        .. note:: This feature is new as of Pyramid 1.2.
+        .. versionadded:: 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
diff --git a/pyramid/config/views.py b/pyramid/config/views.py
index e4217f2f3..de96363de 100644
--- a/pyramid/config/views.py
+++ b/pyramid/config/views.py
@@ -710,7 +710,7 @@ class ViewsConfiguratorMixin(object):
 
         http_cache
 
-          .. note:: This feature is new as of Pyramid 1.1.
+          .. versionadded:: 1.1
 
           When you supply an ``http_cache`` value to a view configuration,
           the ``Expires`` and ``Cache-Control`` headers of a response
@@ -877,9 +877,9 @@ class ViewsConfiguratorMixin(object):
           supplied value.  Note that use of ``GET`` also implies that the
           view will respond to ``HEAD`` as of Pyramid 1.4.
 
-          .. note:: The ability to pass a tuple of items as
-                   ``request_method`` is new as of Pyramid 1.2.  Previous
-                   versions allowed only a string.
+          .. versionchanged:: 1.2
+             The ability to pass a tuple of items as ``request_method`` is
+             new as of Pyramid 1.2.  Previous versions allowed only a string.
 
         request_param
 
@@ -897,7 +897,7 @@ class ViewsConfiguratorMixin(object):
 
         match_param
 
-          .. note:: This feature is new as of :app:`Pyramid` 1.2.
+          .. versionadded:: 1.2
 
           This value can be a string of the format "key=value" or a tuple
           containing one or more of these strings.
@@ -1354,7 +1354,10 @@ class ViewsConfiguratorMixin(object):
     @action_method
     def add_view_predicate(self, name, factory, weighs_more_than=None,
                            weighs_less_than=None):
-        """ Adds a view predicate factory.  The associated view predicate can
+        """
+        .. versionadded:: 1.4
+
+        Adds a view predicate factory.  The associated view predicate can
         later be named as a keyword argument to
         :meth:`pyramid.config.Configurator.add_view` in the
         ``predicates`` anonyous keyword argument dictionary.
@@ -1366,10 +1369,6 @@ class ViewsConfiguratorMixin(object):
         ``factory`` should be a :term:`predicate factory`.
 
         See :ref:`view_and_route_predicates` for more information.
-
-        .. note::
-
-           This method is new as of Pyramid 1.4.
         """
         self._add_predicate(
             'view',
@@ -1557,9 +1556,7 @@ class ViewsConfiguratorMixin(object):
         ``for_``, or ``http_cache`` keyword arguments.  These argument values
         make no sense in the context of a forbidden view.
 
-        .. note::
-
-           This method is new as of Pyramid 1.3.
+        .. versionadded:: 1.3
         """
         for arg in ('name', 'permission', 'context', 'for_', 'http_cache'):
             if arg in predicates:
@@ -1646,9 +1643,7 @@ class ViewsConfiguratorMixin(object):
         Pyramid will return the result of the view callable provided as
         ``view``, as normal.
 
-        .. note::
-
-           This method is new as of Pyramid 1.3.
+        .. versionadded:: 1.3
         """
         for arg in ('name', 'permission', 'context', 'for_', 'http_cache'):
             if arg in predicates: