minor #4845 Add documention note about variable scope of override blocks in {% embed ... only %} (andy-blum)

This PR was squashed before being merged into the 3.x branch.

Discussion
----------

Add documention note about variable scope of override blocks in {% embed ... only %}

Closes #4844

Commits
-------

068a2e6cb4 Add documention note about variable scope of override blocks in {% embed ... only %}

doc/tags/embed.rst

@@ -73,7 +73,7 @@ two boxes side by side:
     ┌─── page layout ─────────────────────┐
     │                                     │
     │           ┌── block "content" ──┐   │
-    │           │                     │   │    
+    │           │                     │   │
     │           │ ┌ block ┐ ┌ block ┐ │   │
     │           │ │"left" │ │"right"│ │   │
     │           │ │       │ │       │ │   │
@@ -164,6 +164,30 @@ The ``embed`` tag takes the exact same arguments as the ``include`` tag:
         ...
     {% endembed %}
 
+.. note::
+
+    Blocks you override inside an ``embed`` are evaluated in the embedded
+    template's context, not the context of the template containing the
+    ``embed`` tag. As with ``include``, embedded templates have access to the
+    variables of the active context. You can disable access to the context by
+    appending the ``only`` keyword. This prevents override blocks
+    from accessing the surrounding context, so any variable they need must also
+    be passed explicitly through ``with``:
+
+    .. code-block:: twig
+
+        {% set name = 'Fabien' %}
+
+        {# "name" is undefined inside the block #}
+        {% embed "base" only %}
+            {% block content %}{{ name }}{% endblock %}
+        {% endembed %}
+
+        {# "name" is passed explicitly and is available #}
+        {% embed "base" with {'name': name} only %}
+            {% block content %}{{ name }}{% endblock %}
+        {% endembed %}
+
 .. warning::
 
     As embedded templates do not have "names", auto-escaping strategies based

doc/tags/include.rst

@@ -108,3 +108,7 @@ inclusion. The first template that exists will be included:
 
 If ``ignore missing`` is given, it will fall back to rendering nothing if none
 of the templates exist, otherwise it will throw an exception.
+
+.. seealso::
+
+    :doc:`embed<../tags/embed>` allows you to include another template's contents like ``include``, but also allows you to override blocks defined inside the included template.