Doc tweaks.

4 files changed, 21 insertions, 8 deletions

diff --git a/repoze/bfg/push.py b/repoze/bfg/push.py
index 205c7f26e..49b9cda27 100644
--- a/repoze/bfg/push.py
+++ b/repoze/bfg/push.py
@@ -2,13 +2,19 @@ import os.path
 from repoze.bfg.template import render_template
 
 class pushpage(object):
-    """ Decorator for functions which return template namespaces.
+    """ Decorator for functions which return ZPT template namespaces.
 
-    E.g.:
+    E.g.::
 
       @pushpage('www/my_template.pt')
       def my_view(context, request):
           return {'a': 1, 'b': ()}
+
+    Equates to::
+
+      def my_view(context, request):
+          return render_template('www/my_template.pt', a=1, b=())
+        
     """
     def __init__(self, template):
         self.template = template
diff --git a/repoze/bfg/router.py b/repoze/bfg/router.py
index 9dd590fc0..791d6772e 100644
--- a/repoze/bfg/router.py
+++ b/repoze/bfg/router.py
@@ -54,12 +54,12 @@ class Router:
 
 def make_app(root_policy, package=None, filename='configure.zcml'):
     """ Create a view registry based on the application's ZCML.  and
-    return a Router object, representing a repoze.bfg WSGI
-    application.  'root_policy' must be a callable that accepts an
-    environ and returns a graph root object.  'package' is the
+    return a Router object, representing a ``repoze.bfg`` WSGI
+    application.  'root_policy' must be a callable that accepts a WSGI
+    environment and returns a graph root object.  'package' is the
     dotted-Python-path packagename of the application, 'filename' is
-    the ZCML file (relative to the package path) that should be parsed
-    to create the view registry."""
+    the filesystem path to a ZCML file (optionally relative to the
+    package path) that should be parsed to create the view registry."""
     from repoze.bfg.registry import makeRegistry
     registry = makeRegistry(filename, package)
     return Router(root_policy, registry)
diff --git a/repoze/bfg/template.py b/repoze/bfg/template.py
index dd0778a43..78529eb40 100644
--- a/repoze/bfg/template.py
+++ b/repoze/bfg/template.py
@@ -70,6 +70,9 @@ def registerTemplate(template, path):
         sm.registerUtility(template, IView, name=path)
 
 def render_template(path, **kw):
+    """ Render a z3c.pt (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. """
     # XXX use pkg_resources
 
     if not os.path.isabs(path):
@@ -90,6 +93,9 @@ def render_template(path, **kw):
     return template(**kw)
 
 def render_transform(path, **kw):
+    """ Render a XSL template at the package-relative path (may also
+    be absolute) using the kwargs in ``*kw`` as top-level names and
+    return a Response object."""
     # Render using XSLT
 
     if not os.path.isabs(path):
diff --git a/repoze/bfg/view.py b/repoze/bfg/view.py
index e2ea156a0..5d5750cea 100644
--- a/repoze/bfg/view.py
+++ b/repoze/bfg/view.py
@@ -5,7 +5,8 @@ from repoze.bfg.interfaces import IView
 from repoze.bfg.interfaces import IViewFactory
 
 class View(object):
-    """ Convenience base class for user-defined views """
+    """ Convenience base class for user-defined views (just accepts
+    context and request)"""
     implements(IView)
     classProvides(IViewFactory)
     def __init__(self, context, request):