A couple of documentation improvements.

4 files changed, 42 insertions, 21 deletions

diff --git a/docs/pages/advanced_topics/asyncio.rst b/docs/pages/advanced_topics/asyncio.rst
index 4e6dfc1e..d34d125c 100644
--- a/docs/pages/advanced_topics/asyncio.rst
+++ b/docs/pages/advanced_topics/asyncio.rst
@@ -14,7 +14,15 @@ line of code, it is possible to run prompt_toolkit on top of asyncio:
     use_asyncio_event_loop()
 
 This will create an adaptor between the asyncio event loop and prompt_toolkit,
-and register it as the default event loop.
+and register it as the underlying event loop for the prompt_toolkit
+application.
+
+When doing this, remember that prompt_toolkit still has its own implementation
+of futures (and coroutines). A prompt_toolkit `Future` needs to be converted to
+an asyncio `Future` for use in an asyncio context, like asyncio's
+``run_until_complete``. The cleanest way is to call
+:meth:`~prompt_toolkit.eventloop.Future.to_asyncio_future`.
+
 
 .. warning::
 
@@ -22,3 +30,6 @@ and register it as the default event loop.
     the preferred way. It's better to avoid the built-in coroutines, because
     they make debugging the application much more difficult. Unless of course
     Python 2 support is still required.
+
+    At some point, when we drop Python 2 support, prompt_toolkit will probably
+    use asyncio natively.
diff --git a/docs/pages/printing_text.rst b/docs/pages/printing_text.rst
index a40ff003..027401ca 100644
--- a/docs/pages/printing_text.rst
+++ b/docs/pages/printing_text.rst
@@ -84,26 +84,22 @@ italic and underline: ``<b>``, ``<i>`` and ``<u>``.
     from __future__ import unicode_literals, print_function
     from prompt_toolkit import print_formatted_text, HTML
 
-    print = print_formatted_text
-
-    print(HTML('<b>This is bold</b>'))
-    print(HTML('<i>This is italic</b>'))
-    print(HTML('<u>This is underlined</u>'))
+    print_formatted_text(HTML('<b>This is bold</b>'))
+    print_formatted_text(HTML('<i>This is italic</b>'))
+    print_formatted_text(HTML('<u>This is underlined</u>'))
 
 Further, it's possible to use tags for foreground colors:
 
 .. code:: python
 
-    print = print_formatted_text
-
     # Colors from the ANSI palette.
-    print(HTML('<ansired>This is red</ansired>'))
-    print(HTML('<ansigreen>This is green</ansigreen>'))
+    print_formatted_text(HTML('<ansired>This is red</ansired>'))
+    print_formatted_text(HTML('<ansigreen>This is green</ansigreen>'))
 
     # Named colors (256 color palette, or true color, depending on the output).
-    print(HTML('<skyblue>This is light pink</skyblue>'))
-    print(HTML('<seagreen>This is light pink</seagreen>'))
-    print(HTML('<violet>This is light pink</violet>'))
+    print_formatted_text(HTML('<skyblue>This is light pink</skyblue>'))
+    print_formatted_text(HTML('<seagreen>This is light pink</seagreen>'))
+    print_formatted_text(HTML('<violet>This is light pink</violet>'))
 
 Both foreground and background colors can also be specified setting the `fg`
 and `bg` attributes of any tag:
diff --git a/docs/pages/progress_bars.rst b/docs/pages/progress_bars.rst
index 2a2c958d..7f237275 100644
--- a/docs/pages/progress_bars.rst
+++ b/docs/pages/progress_bars.rst
@@ -114,14 +114,12 @@ Both the title and the labels can be :ref:`formatted text <formatted_text>`.
     from prompt_toolkit.formatted_text import HTML
     import time
 
+    title = HTML('Downloading <style bg="yellow" fg="black">4 files...</style>')
+    label = HTML('<ansired>some file</ansired>: ')
 
-    def main():
-        title = HTML('Downloading <style bg="yellow" fg="black">4 files...</style>')
-        label = HTML('<ansired>some file</ansired>: ')
-
-        with ProgressBar(title=title) as pb:
-            for i in pb(range(800), label=label):
-                time.sleep(.01)
+    with ProgressBar(title=title) as pb:
+        for i in pb(range(800), label=label):
+            time.sleep(.01)
 
 .. image:: ../images/progress-bars/colored-title-and-label.png
 
diff --git a/prompt_toolkit/application/application.py b/prompt_toolkit/application/application.py
index 72f084ca..2e4e359c 100644
--- a/prompt_toolkit/application/application.py
+++ b/prompt_toolkit/application/application.py
@@ -492,7 +492,23 @@ class Application(object):
 
     def run_async(self, pre_run=None):
         """
-        Run asynchronous. Return a `Future` object.
+        Run asynchronous. Return a prompt_toolkit
+        :class:`~prompt_toolkit.eventloop.Future` object.
+
+        If you wish to run on top of asyncio, remember that a prompt_toolkit
+        `Future` needs to be converted to an asyncio `Future`. The cleanest way
+        is to call :meth:`~prompt_toolkit.eventloop.Future.to_asyncio_future`.
+        Also make sure to tell prompt_toolkit to use the asyncio event loop.
+
+        .. code:: python
+
+            from prompt_toolkit.eventloop import use_asyncio_event_loop
+            from asyncio import get_event_loop
+
+            use_asyncio_event_loop()
+            get_event_loop().run_until_complete(
+                application.run_async().to_asyncio_future())
+
         """
         assert not self._is_running