update docs about required blocks (#1340)

diff --git a/CHANGES.rst b/CHANGES.rst
index 658d2d37f13797a203d0c20de8da1846d868b162..b5c4df29f0af9c21473c8de85dbaa2bdce067050 100644 (file)
--- a/CHANGES.rst
+++ b/CHANGES.rst
@@ -19,9 +19,10 @@ Unreleased
 -   Fix UndefinedError incorrectly being thrown on an undefined variable
     instead of ``Undefined`` being returned on
     ``NativeEnvironment`` on Python 3.10. :issue:`1335`
--   Add ``required`` attribute to blocks that must be overridden at some
-    point, but not necessarily by the direct child :issue:`1147`
--   Deprecate ``autoescape`` and ``with`` extensions :issue:`1203`
+-   Blocks can be marked as ``required``. They must be overridden at
+    some point, but not necessarily by the direct child. :issue:`1147`
+-   Deprecate the ``autoescape`` and ``with`` extensions, they are
+    built-in to the compiler. :issue:`1203`
 
 
 Version 2.11.2

diff --git a/docs/templates.rst b/docs/templates.rst
index 58ed870ef77a520793ac35d7d087dc245ddc34b8..6226468dbf8153255063b2caeda7cc1eefbf35f5 100644 (file)
--- a/docs/templates.rst
+++ b/docs/templates.rst
@@ -541,33 +541,38 @@ 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.
+Blocks can be marked as ``required``. They must be overridden at some
+point, but not necessarily by the direct child template. Required blocks
+may only contain space and comments, and they cannot be rendered
+directly.
 
-For example::
+.. code-block:: jinja
+    :caption: ``page.txt``
 
-    # parent.tmpl
-    body: {% block body required %}{% endblock %}
+    {% block body required %}{% endblock %}
 
-    # child.tmpl
-    {% extends "parent.tmpl" %}
+.. code-block:: jinja
+    :caption: ``issue.txt``
 
-    # grandchild.tmpl
-    {% extends "child.tmpl" %}
-    {% block body %}Hi from grandchild.{% endblock %}
+    {% extends "page.txt" %}
 
+.. code-block:: jinja
+    :caption: ``bug_report.txt``
 
-Rendering ``child.tmpl`` will give
-``TemplateRuntimeError``
+    {% extends "issue.txt" %}
+    {% block body %}Provide steps to demonstrate the bug.{% endblock %}
+
+Rendering ``page.txt`` or ``issue.txt`` will raise
+``TemplateRuntimeError`` because they don't override the ``body`` block.
+Rendering ``bug_report.txt`` will succeed because it does override the
+block.
 
-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:
 
-When combined with ``scoped``, the ``required`` modifier must be placed `after`
-the scoped modifier.  Here are some valid examples::
+.. code-block:: jinja
 
     {% block body scoped %}{% endblock %}
     {% block body required %}{% endblock %}