From 1c3b53c5db3c9c0f7a1f1650b020e6302705395b Mon Sep 17 00:00:00 2001
From: pgjones <philip.graham.jones@googlemail.com>
Date: Sat, 17 Apr 2021 11:27:38 +0100
Subject: [PATCH] Update the docs on serving with ASGI

Whilst it has been possible to serve via an ASGI server for a while
(using WSGI to ASGI middleware/adapters) it hasn't added much. Now
though it makes sense to recommend the asgiref adapter as it
integrates with the same event loop used for async route handlers
etc...
---
 docs/deploying/asgi.rst  | 27 +++++++++++++++++++++++++++
 docs/deploying/index.rst |  1 +
 2 files changed, 28 insertions(+)
 create mode 100644 docs/deploying/asgi.rst

diff --git a/docs/deploying/asgi.rst b/docs/deploying/asgi.rst
new file mode 100644
index 00000000..6e70fee7
--- /dev/null
+++ b/docs/deploying/asgi.rst
@@ -0,0 +1,27 @@
+ASGI
+====
+
+If you'd like to use an ASGI server you will need to utilise WSGI to
+ASGI middleware. The asgiref
+[WsgiToAsgi](https://github.com/django/asgiref#wsgi-to-asgi-adapter)
+adapter is recommended as it integrates with the event loop used for
+Flask's :ref:`async_await` support. You can use the adapter by
+wrapping the Flask app,
+
+.. code-block:: python
+
+    from asgiref.wsgi import WsgiToAsgi
+    from flask import Flask
+
+    app = Flask(__name__)
+
+    ...
+
+    asgi_app = WsgiToAsgi(app)
+
+and then serving the ``asgi_app`` with the asgi server, e.g. using
+`Hypercorn <https://gitlab.com/pgjones/hypercorn>`_,
+
+.. sourcecode:: text
+
+    $ hypercorn module:asgi_app
diff --git a/docs/deploying/index.rst b/docs/deploying/index.rst
index 54380599..4511bf45 100644
--- a/docs/deploying/index.rst
+++ b/docs/deploying/index.rst
@@ -31,3 +31,4 @@ Self-hosted options
    mod_wsgi
    fastcgi
    cgi
+   asgi