Merge pull request #820 from tshepang/master

some renderers and view API doc improvements

2 files changed, 29 insertions, 35 deletions

diff --git a/pyramid/renderers.py b/pyramid/renderers.py
index 6839d72f5..6310b7fee 100644
--- a/pyramid/renderers.py
+++ b/pyramid/renderers.py
@@ -43,23 +43,23 @@ from pyramid.threadlocal import get_current_registry
 # API
 
 def render(renderer_name, value, request=None, package=None):
-    """ Using the renderer specified as ``renderer_name`` (a template
-    or a static renderer) render the value (or set of values) present
+    """ Using the renderer ``renderer_name`` (a template
+    or a static renderer), render the value (or set of values) present
     in ``value``. Return the result of the renderer's ``__call__``
     method (usually a string or Unicode).
 
-    If the renderer name refers to a file on disk (such as when the
-    renderer is a template), it's usually best to supply the name as a
+    If the ``renderer_name`` refers to a file on disk, such as when the
+    renderer is a template, it's usually best to supply the name as an
     :term:`asset specification`
     (e.g. ``packagename:path/to/template.pt``).
 
     You may supply a relative asset spec as ``renderer_name``.  If
     the ``package`` argument is supplied, a relative renderer path
     will be converted to an absolute asset specification by
-    combining the package supplied as ``package`` with the relative
-    asset specification supplied as ``renderer_name``.  If you do
-    not supply a ``package`` (or ``package`` is ``None``) the package
-    name of the *caller* of this function will be used as the package.
+    combining the package ``package`` with the relative
+    asset specification ``renderer_name``.  If ``package``
+    is ``None`` (the default), the package name of the *caller* of
+    this function will be used as the package.
 
     The ``value`` provided will be supplied as the input to the
     renderer.  Usually, for template renderings, this should be a
@@ -70,7 +70,7 @@ def render(renderer_name, value, request=None, package=None):
     top-level system names, such as ``request``, ``context``,
     ``renderer_name``, and ``view``.  See :ref:`renderer_system_values` for
     the full list.  If :term:`renderer globals` have been specified, these
-    will also be used to agument the value.
+    will also be used to augment the value.
 
     Supply a ``request`` parameter in order to provide the renderer
     with the most correct 'system' values (``request`` and ``context``
@@ -88,8 +88,8 @@ def render(renderer_name, value, request=None, package=None):
     return helper.render(value, None, request=request)
 
 def render_to_response(renderer_name, value, request=None, package=None):
-    """ Using the renderer specified as ``renderer_name`` (a template
-    or a static renderer) render the value (or set of values) using
+    """ Using the renderer ``renderer_name`` (a template
+    or a static renderer), render the value (or set of values) using
     the result of the renderer's ``__call__`` method (usually a string
     or Unicode) as the response body.
 
@@ -100,8 +100,8 @@ def render_to_response(renderer_name, value, request=None, package=None):
     You may supply a relative asset spec as ``renderer_name``.  If
     the ``package`` argument is supplied, a relative renderer name
     will be converted to an absolute asset specification by
-    combining the package supplied as ``package`` with the relative
-    asset specification supplied as ``renderer_name``.  If you do
+    combining the package ``package`` with the relative
+    asset specification ``renderer_name``.  If you do
     not supply a ``package`` (or ``package`` is ``None``) the package
     name of the *caller* of this function will be used as the package.
 
@@ -134,16 +134,15 @@ def render_to_response(renderer_name, value, request=None, package=None):
     return helper.render_to_response(value, None, request=request)
 
 def get_renderer(renderer_name, package=None):
-    """ Return the renderer object for the renderer named as
-    ``renderer_name``.
+    """ Return the renderer object for the renderer ``renderer_name``.
 
     You may supply a relative asset spec as ``renderer_name``.  If
     the ``package`` argument is supplied, a relative renderer name
     will be converted to an absolute asset specification by
-    combining the package supplied as ``package`` with the relative
-    asset specification supplied as ``renderer_name``.  If you do
-    not supply a ``package`` (or ``package`` is ``None``) the package
-    name of the *caller* of this function will be used as the package.
+    combining the package ``package`` with the relative
+    asset specification ``renderer_name``.  If ``package`` is ``None``
+    (the default), the package name of the *caller* of this function
+    will be used as the package.
     """
     if package is None:
         package = caller_package()
diff --git a/pyramid/view.py b/pyramid/view.py
index 40d7c19b9..b88c2ea85 100644
--- a/pyramid/view.py
+++ b/pyramid/view.py
@@ -29,9 +29,11 @@ _marker = object()
 class static(static_view):
     """ Backwards compatibility alias for
     :class:`pyramid.static.static_view`; it overrides that class' constructor
-    to pass ``use_subpath=True`` by default.  This class is deprecated as of
-    :app:`Pyramid` 1.1.  Use :class:`pyramid.static.static_view` instead
-    (probably with a ``use_subpath=True`` argument).
+    to pass ``use_subpath=True`` by default.
+
+    .. deprecated:: 1.1
+       use :class:`pyramid.static.static_view` instead
+       (probably with a ``use_subpath=True`` argument)
     """
     def __init__(self, root_dir, cache_max_age=3600, package_name=None):
         if package_name is None:
@@ -312,11 +314,12 @@ See also :ref:`changing_the_notfound_view`.
 
 class notfound_view_config(object):
     """
+    .. versionadded:: 1.3
 
     An analogue of :class:`pyramid.view.view_config` which registers a
-    :term:`not found view`.
+    :term:`Not Found View`.
 
-    The notfound_view_config constructor accepts most of the same arguments
+    The ``notfound_view_config`` constructor accepts most of the same arguments
     as the constructor of :class:`pyramid.view.view_config`.  It can be used
     in the same places, and behaves in largely the same way, except it always
     registers a not found exception view instead of a 'normal' view.
@@ -346,9 +349,6 @@ class notfound_view_config(object):
 
     See :ref:`changing_the_notfound_view` for detailed usage information.
 
-    .. note::
-
-       This class is new as of Pyramid 1.3.
     """
 
     venusian = venusian
@@ -377,6 +377,7 @@ class notfound_view_config(object):
 
 class forbidden_view_config(object):
     """
+    .. versionadded:: 1.3
 
     An analogue of :class:`pyramid.view.view_config` which registers a
     :term:`forbidden view`.
@@ -403,9 +404,6 @@ class forbidden_view_config(object):
 
     See :ref:`changing_the_forbidden_view` for detailed usage information.
 
-    .. note::
-
-       This class is new as of Pyramid 1.3.
     """
 
     venusian = venusian
@@ -436,11 +434,8 @@ def is_response(ob):
     """ Return ``True`` if ``ob`` implements the interface implied by
     :ref:`the_response`. ``False`` if not.
 
-    .. warning::
-
-       This function is deprecated as of :app:`Pyramid` 1.1.  New
-       code should not use it.  Instead, new code should use the
-       :func:`pyramid.request.Request.is_response` method."""
+    .. deprecated:: 1.1
+       use :func:`pyramid.request.Request.is_response` instead"""
     if ( hasattr(ob, 'app_iter') and hasattr(ob, 'headerlist') and
          hasattr(ob, 'status') ):
         return True