added docs and changes for using defs in mako renderer

3 files changed, 28 insertions, 0 deletions

diff --git a/CHANGES.txt b/CHANGES.txt
index 7c2af4451..3cb2f2848 100644
--- a/CHANGES.txt
+++ b/CHANGES.txt
@@ -41,3 +41,8 @@ Features
 - The static view machinery now raises (rather than returns) ``HTTPNotFound``
   and ``HTTPMovedPermanently`` exceptions, so these can be caught by the
   NotFound view (and other exception views).
+
+- The mako renderer now accepts a def name and returns the template def 
+  result for the view being called. The uri format using an asset spec is 
+  package:path/to/template#defname.mako. The old way of returning a tuple 
+  from the view is supported for backward compatibility, ('defname', {}).
diff --git a/docs/narr/templates.rst b/docs/narr/templates.rst
index 9db0b1c4d..4ac01c96e 100644
--- a/docs/narr/templates.rst
+++ b/docs/narr/templates.rst
@@ -714,6 +714,22 @@ This template doesn't use any advanced features of Mako, only the
 :term:`renderer globals`.  See the `the Mako documentation
 <http://www.makotemplates.org/>`_ to use more advanced features.
 
+Using def inside Mako Templates
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To use a def inside a Mako template, given a :term:`Mako` template file named 
+``foo.mak`` and a def named ``bar``, you can configure the template as a 
+:term:`renderer` like so:
+
+.. code-block:: python
+   :linenos:
+
+   from pyramid.view import view_config
+
+   @view_config(renderer='foo#defname.mak')
+   def my_view(request):
+       return {'project':'my project'}
+
 .. index::
    single: automatic reloading of templates
    single: template automatic reload
diff --git a/pyramid/mako_templating.py b/pyramid/mako_templating.py
index b02daa23c..bb4ccb2f0 100644
--- a/pyramid/mako_templating.py
+++ b/pyramid/mako_templating.py
@@ -163,6 +163,13 @@ class MakoRenderingException(Exception):
 
 @implementer(ITemplateRenderer)
 class MakoLookupTemplateRenderer(object):
+    """ Render a :term:`Mako` template using the template
+    implied by the ``path`` argument.The ``path`` argument may be a
+    package-relative path, an absolute path, or a :term:`asset
+    specification`. If a defname is defined, in the form of 
+    package:path/to/template#defname.mako, a function named ``defname`` 
+    inside the template will then be rendered.
+    """
     def __init__(self, path, defname, lookup):
         self.path = path
         self.defname = defname