add required attribute to blocks

required blocks must be overridden at some point, although not
necessarily by the direct child template

1 files changed, 34 insertions, 0 deletions

diff --git a/docs/templates.rst b/docs/templates.rst
index 14de875..58ed870 100644
--- a/docs/templates.rst
+++ b/docs/templates.rst
@@ -540,6 +540,40 @@ modifier to a block declaration::
 When overriding a block, the `scoped` modifier does not have to be provided.
 
 
+Required Blocks
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Blocks can be marked as required. They must be overridden at some point,
+but not necessarily by the direct child template. Required blocks can
+only contain whitespace or comments, and they cannot be rendered directly.
+
+For example::
+
+    # parent.tmpl
+    body: {% block body required %}{% endblock %}
+
+    # child.tmpl
+    {% extends "parent.tmpl" %}
+
+    # grandchild.tmpl
+    {% extends "child.tmpl" %}
+    {% block body %}Hi from grandchild.{% endblock %}
+
+
+Rendering ``child.tmpl`` will give
+``TemplateRuntimeError``
+
+Rendering ``grandchild.tmpl`` will give
+``Hi from grandchild.``
+
+When combined with ``scoped``, the ``required`` modifier must be placed `after`
+the scoped modifier.  Here are some valid examples::
+
+    {% block body scoped %}{% endblock %}
+    {% block body required %}{% endblock %}
+    {% block body scoped required %}{% endblock %}
+
+
 Template Objects
 ~~~~~~~~~~~~~~~~