added doc for the sandbox tag

diff --git a/doc/tags/include.rst b/doc/tags/include.rst
index 7bba404..9bae35c 100644 (file)
--- a/doc/tags/include.rst
+++ b/doc/tags/include.rst
@@ -41,7 +41,7 @@ You can disable access to the context by appending the ``only`` keyword:
 
     When including a template created by an end user, you should consider
     sandboxing it. More information in the :doc:`Twig for Developers<../api>`
-    chapter.
+    chapter and in the :doc:`<sandbox>` tag documentation.
 
 The template name can be any valid Twig expression:
 

diff --git a/doc/tags/sandbox.rst b/doc/tags/sandbox.rst
new file mode 100644 (file)
index 0000000..22a534f
--- /dev/null
+++ b/doc/tags/sandbox.rst
@@ -0,0 +1,30 @@
+``sandbox``
+===========
+
+The ``sandbox`` tag can be used to enable the sandboxing mode for an included
+template, when sandboxing is not enabled globally for the Twig environment::
+
+.. code-block:: jinja
+
+    {% sandbox %}
+        {% include 'user.html' %}
+    {% endsandbox %}
+
+.. warning::
+
+    The ``sandbox`` tag is only available when the sandbox extension is
+    enabled (see the :doc:`Twig for Developers<../api>` chapter).
+
+.. note::
+
+    The ``sandbox`` tag can only be used to sandbox an include tag and it
+    cannot be used to sandbox a section of a template. The following example
+    won't work for example::
+
+    .. code-block:: jinja
+
+        {% sandbox %}
+            {% for i in 1..2 %}
+                {{ i }}
+            {% endfor %}
+        {% endsandbox %}