Started doc work for async

diff --git a/docs/api.rst b/docs/api.rst
index 6de5a1db969bc1650f54ebc42e6491e1d63150dd..6c2e71aa37f7f60e05dcd0a2980ea217d901fece 100644 (file)
--- a/docs/api.rst
+++ b/docs/api.rst
@@ -229,6 +229,10 @@ useful if you want to dig deeper into Jinja2 or :ref:`develop extensions
 
     .. automethod:: stream([context])
 
+    .. automethod:: render_async([context])
+
+    .. automethod:: generate_async([context])
+
 
 .. autoclass:: jinja2.environment.TemplateStream()
     :members: disable_buffering, enable_buffering, dump
@@ -497,6 +501,42 @@ Builtin bytecode caches:
 .. autoclass:: jinja2.MemcachedBytecodeCache
 
 
+Async Support
+-------------
+
+Starting with version 2.9, Jinja2 also supports the Python `async` and
+`await` constructs.  As far as template designers go this feature is
+entirely opaque to them however as a developer you should be aware of how
+it's implemented as it influences what type of APIs you can safely expose
+to the template environment.
+
+First you need to be aware that by default async support is disabled as
+enabling it will generate different template code behind the scenes which
+passes everything through the asyncio event loop.  This is important to
+understand because it has some impact to what you are doing:
+
+*   template rendering will require an event loop to be set for the
+    current thread (``asyncio.get_event_loop`` needs to return one)
+*   all template generation code internally runs async generators which
+    means that you will pay a performance penalty even if the non sync
+    methods are used!
+*   The sync methods are based on async methods if the async mode is
+    enabled which means that `render` for instance will internally invoke
+    `render_async` and run it as part of the current event loop until the
+    execution finished.
+
+Awaitable objects can be returned from functions in templates and any
+function call in a template will automatically await the result.  This
+means that you can let provide a method that asynchronously loads data
+from a database if you so desire and from the template designer's point of
+view this is just another function they can call.  This means that the
+``await`` you would normally issue in Python is implied.  However this
+only applies to function calls.  If an attribute for instance would be an
+avaitable object then this would not result in the expected behavior.
+
+Likewise iterations with a `for` loop support async iterators.
+
+
 Utilities
 ---------