From 5cd7be3ea65ec81245136ab28161cdf2d4457889 Mon Sep 17 00:00:00 2001
From: Chris McDonough <chrism@agendaless.com>
Date: Thu, 24 Dec 2009 00:53:12 +0000
Subject: Better API docs.

---
 repoze/bfg/chameleon_text.py | 34 ++++++++++++++++++++++------------
 repoze/bfg/chameleon_zpt.py  | 34 ++++++++++++++++++++++------------
 2 files changed, 44 insertions(+), 24 deletions(-)

diff --git a/repoze/bfg/chameleon_text.py b/repoze/bfg/chameleon_text.py
index 6a9fb7c6c..85f0126b3 100644
--- a/repoze/bfg/chameleon_text.py
+++ b/repoze/bfg/chameleon_text.py
@@ -61,29 +61,39 @@ class TextTemplateRenderer(object):
         return result
 
 def get_renderer(path):
-    """ Return a callable ``ITemplateRenderer`` object representing a
-    ``Chameleon`` text template at the package-relative path (may also
-    be absolute)."""
+    """ Return a callable object which can be used to render a
+    :term:`Chameleon` text template using the template implied by the
+    ``path`` argument.  The ``path`` argument may be a
+    package-relative path, an absolute path, or a :term:`resource
+    specification`."""
     return renderer_factory(path)
 
 def get_template(path):
-    """ Return a ``Chameleon`` text template at the package-relative
-    path (may also be absolute)."""
+    """ Return the underyling object representing a :term:`Chameleon`
+    text template using the template implied by the ``path`` argument.
+    The ``path`` argument may be a package-relative path, an absolute
+    path, or a :term:`resource specification`."""
     renderer = renderer_factory(path)
     return renderer.implementation()
 
 def render_template(path, **kw):
-    """ Render a ``chameleon`` text template at the package-relative
-    path (may also be absolute) using the kwargs in ``*kw`` as
-    top-level names and return a string."""
+    """ Render a :term:`Chameleon` text template using the template
+    implied by the ``path`` argument.  The ``path`` argument may be a
+    package-relative path, an absolute path, or a :term:`resource
+    specification`.  The arguments in ``*kw`` are passed as top-level
+    names to the template, and so may be used within the template
+    itself.  Returns a string."""
     renderer = renderer_factory(path)
     return renderer(kw, {})
 
 def render_template_to_response(path, **kw):
-    """ Render a ``chameleon`` text template at the package-relative
-    path (may also be absolute) using the kwargs in ``*kw`` as
-    top-level names and return a Response object with the body as the
-    template result."""
+    """ Render a :term:`Chameleon` text template using the template
+    implied by the ``path`` argument.  The ``path`` argument may be a
+    package-relative path, an absolute path, or a :term:`resource
+    specification`.  The arguments in ``*kw`` are passed as top-level
+    names to the template, and so may be used within the template
+    itself.  Returns a :term:`Response` object with the body as the
+    template result.."""
     renderer = renderer_factory(path)
     result = renderer(kw, {})
     reg = get_current_registry()
diff --git a/repoze/bfg/chameleon_zpt.py b/repoze/bfg/chameleon_zpt.py
index d6105a5b6..764919cc3 100644
--- a/repoze/bfg/chameleon_zpt.py
+++ b/repoze/bfg/chameleon_zpt.py
@@ -44,29 +44,39 @@ class ZPTTemplateRenderer(object):
         return result
 
 def get_renderer(path):
-    """ Return a callable ``ITemplateRenderer`` object representing a
-    ``chameleon.zpt`` template at the package-relative path (may also
-    be absolute). """
+    """ Return a callable object which can be used to render a
+    :term:`Chameleon` ZPT template using the template implied by the
+    ``path`` argument.  The ``path`` argument may be a
+    package-relative path, an absolute path, or a :term:`resource
+    specification`."""
     return renderer_factory(path)
 
 def get_template(path):
-    """ Return a ``chameleon.zpt`` template at the package-relative
-    path (may also be absolute).  """
+    """ Return the underyling object representing a :term:`Chameleon`
+    ZPT template using the template implied by the ``path`` argument.
+    The ``path`` argument may be a package-relative path, an absolute
+    path, or a :term:`resource specification`."""
     renderer = renderer_factory(path)
     return renderer.implementation()
 
 def render_template(path, **kw):
-    """ Render a ``chameleon.zpt`` template at the package-relative
-    path (may also be absolute) using the kwargs in ``*kw`` as
-    top-level names and return a string."""
+    """ Render a :term:`Chameleon` ZPT template using the template
+    implied by the ``path`` argument.  The ``path`` argument may be a
+    package-relative path, an absolute path, or a :term:`resource
+    specification`.  The arguments in ``*kw`` are passed as top-level
+    names to the template, and so may be used within the template
+    itself.  Returns a string."""
     renderer = renderer_factory(path)
     return renderer(kw, {})
 
 def render_template_to_response(path, **kw):
-    """ Render a ``chameleon.zpt`` template at the package-relative
-    path (may also be absolute) using the kwargs in ``*kw`` as
-    top-level names and return a Response object with the body as the
-    template result. """
+    """ Render a :term:`Chameleon` ZPT template using the template
+    implied by the ``path`` argument.  The ``path`` argument may be a
+    package-relative path, an absolute path, or a :term:`resource
+    specification`.  The arguments in ``*kw`` are passed as top-level
+    names to the template, and so may be used within the template
+    itself.  Returns a :term:`Response` object with the body as the
+    template result.."""
     renderer = renderer_factory(path)
     result = renderer(kw, {})
     reg = get_current_registry()
-- 
cgit v1.2.3