From b04ae5ac814266eb77d4a09c749e5e0394a11a1c Mon Sep 17 00:00:00 2001
From: Michael Merickel <michael@digitalartefacts.com>
Date: Sat, 19 Oct 2013 03:43:05 -0500
Subject: modify the docs for the renderer interfaces

---
 CHANGES.txt             |  9 +++++++++
 docs/api/interfaces.rst |  5 ++++-
 pyramid/interfaces.py   | 53 +++++++++++++++++++++++++++++--------------------
 3 files changed, 44 insertions(+), 23 deletions(-)

diff --git a/CHANGES.txt b/CHANGES.txt
index a228fbb3a..10ebe33ae 100644
--- a/CHANGES.txt
+++ b/CHANGES.txt
@@ -40,6 +40,9 @@ Documentation
 - Removed mention of ``pyramid_beaker`` from docs.  Beaker is no longer 
   maintained.  Point people at ``pyramid_redis_sessions`` instead.
 
+- Add documentation for ``pyramid.interfaces.IRendererFactory`` and
+  ``pyramid.interfaces.IRenderer``.
+
 Backwards Incompatibilities
 ---------------------------
 
@@ -50,6 +53,12 @@ Backwards Incompatibilities
   situation, leaving a query string of ``a=b&key=``.
   See https://github.com/Pylons/pyramid/issues/1119
 
+Deprecations
+------------
+
+- Deprecate the ``pyraid.interfaces.ITemplateRenderer`` interface. It is no
+  longer used since Mako and Chameleon have been split into their own packages.
+
 1.5a2 (2013-09-22)
 ==================
 
diff --git a/docs/api/interfaces.rst b/docs/api/interfaces.rst
index 1dea5fab0..d8d935afd 100644
--- a/docs/api/interfaces.rst
+++ b/docs/api/interfaces.rst
@@ -50,7 +50,10 @@ Other Interfaces
   .. autointerface:: IRendererInfo
      :members:
 
-  .. autointerface:: ITemplateRenderer
+  .. autointerface:: IRendererFactory
+     :members:
+
+  .. autointerface:: IRenderer
      :members:
 
   .. autointerface:: IViewMapperFactory
diff --git a/pyramid/interfaces.py b/pyramid/interfaces.py
index 85b2227b4..cf651cf1e 100644
--- a/pyramid/interfaces.py
+++ b/pyramid/interfaces.py
@@ -367,9 +367,29 @@ class IBeforeRender(IDict):
                               '``render`` method for this rendering. '
                               'This feature is new in Pyramid 1.2.')
 
+class IRendererInfo(Interface):
+    """ An object implementing this interface is passed to every
+    :term:`renderer factory` constructor as its only argument (conventionally
+    named ``info``)"""
+    name = Attribute('The value passed by the user as the renderer name')
+    package = Attribute('The "current package" when the renderer '
+                        'configuration statement was found')
+    type = Attribute('The renderer type name')
+    registry = Attribute('The "current" application registry when the '
+                         'renderer was created')
+    settings = Attribute('The deployment settings dictionary related '
+                         'to the current application')
+
+class IRendererFactory(Interface):
+    def __call__(info):
+        """ Return an object that implements
+        :class:`pyramid.interfaces.IRenderer`. ``info`` is an
+        object that implements :class:`pyramid.interfaces.IRendererInfo`.
+        """
+
 class IRenderer(Interface):
     def __call__(value, system):
-        """ Call a the renderer implementation with the result of the
+        """ Call the renderer with the result of the
         view (``value``) passed in and return a result (a string or
         unicode object useful as a response body).  Values computed by
         the system are passed by the system in the ``system``
@@ -387,6 +407,13 @@ class ITemplateRenderer(IRenderer):
         accepts arbitrary keyword arguments and returns a string or
         unicode object """
 
+deprecated(
+    'ITemplateRenderer',
+    'As of Pyramid 1.5 the, "pyramid.interfaces.ITemplateRenderer" interface '
+    'is scheduled to be removed. It was used by the Mako and Chameleon '
+    'renderers which have been split into their own packages.'
+    )
+
 class IViewMapper(Interface):
     def __call__(self, object):
         """ Provided with an arbitrary object (a function, class, or
@@ -611,17 +638,13 @@ class ITraverser(Interface):
 
 ITraverserFactory = ITraverser # b / c for 1.0 code
 
-class IRendererFactory(Interface):
-    def __call__(info):
-        """ Return an object that implements ``IRenderer``.  ``info`` is an
-        object that implement ``IRendererInfo``.  """
-
 class IViewPermission(Interface):
     def __call__(context, request):
-        """ Return True if the permission allows, return False if it denies. """
+        """ Return True if the permission allows, return False if it denies.
+        """
 
 class IRouter(Interface):
-    """WSGI application which routes requests to 'view' code based on
+    """ WSGI application which routes requests to 'view' code based on
     a view registry."""
     registry = Attribute(
         """Component architecture registry local to this application.""")
@@ -932,20 +955,6 @@ class ISession(IDict):
         returned.
         """
 
-class IRendererInfo(Interface):
-    """ An object implementing this interface is passed to every
-    :term:`renderer factory` constructor as its only argument (conventionally
-    named ``info``)"""
-    name = Attribute('The value passed by the user as the renderer name')
-    package = Attribute('The "current package" when the renderer '
-                        'configuration statement was found')
-    type = Attribute('The renderer type name')
-    registry = Attribute('The "current" application registry when the '
-                         'renderer was created')
-    settings = Attribute('The deployment settings dictionary related '
-                         'to the current application')
-
-
 class IIntrospector(Interface):
     def get(category_name, discriminator, default=None):
         """ Get the IIntrospectable related to the category_name and the
-- 
cgit v1.2.3