Add STOP_RENDERING keyword; exiting of a template.

Signed-off-by: Cody Taylor <codemister99@yahoo.com>

2 files changed, 27 insertions, 6 deletions

diff --git a/doc/build/changelog.rst b/doc/build/changelog.rst
index 03aaec7..9c321bb 100644
--- a/doc/build/changelog.rst
+++ b/doc/build/changelog.rst
@@ -6,6 +6,18 @@ Changelog
 ===
 
 .. changelog::
+    :version: 1.0.2
+
+    .. change::
+        :tags: feature
+        :tickets: 236
+
+      Added STOP_RENDERING keyword for returning/exiting from a
+      template early. Previously the docs suggested a bare
+      ``return``, but this could cause ``None`` to appear in the
+      rendered template result.
+
+.. changelog::
     :version: 1.0.1
     :released: Thu Jan 22 2015
 
diff --git a/doc/build/syntax.rst b/doc/build/syntax.rst
index fe4a860..7ec68cb 100644
--- a/doc/build/syntax.rst
+++ b/doc/build/syntax.rst
@@ -443,19 +443,19 @@ Mako:
         <%def name="x()">${x}</%def>
     </%text>
 
-Returning Early from a Template
-===============================
+Exiting Early from a Template
+=============================
 
 Sometimes you want to stop processing a template or ``<%def>``
 method in the middle and just use the text you've accumulated so
-far. You can use a ``return`` statement inside a Python
-block to do that.
+far. You can ``return`` the ``STOP_RENDERING`` value inside a Python
+block to exit the current rendering process.
 
 .. sourcecode:: mako
 
     % if not len(records):
         No records found.
-        <% return %>
+        <% return STOP_RENDERING %>
     % endif
 
 Or perhaps:
@@ -464,6 +464,15 @@ Or perhaps:
 
     <%
         if not len(records):
-            return
+            return STOP_RENDERING
     %>
 
+In older versions, return an empty string instead to avoid having
+``None`` in your rendered template:
+
+.. sourcecode:: mako
+
+    <% return '' %>
+
+.. versionadded:: 1.0.2
+