"In short" and "WSGI to ASGI" doc sections

docs/concepts.rst

@@ -21,6 +21,8 @@ view is called.
 
 Let's look at what *channels* are first.
 
+.. _what-are-channels:
+
 What is a channel?
 ------------------
 

docs/deploying.rst

@@ -118,7 +118,7 @@ first, make sure your project has an ``asgi.py`` file that looks like this
 
     channel_layer = get_channel_layer()
 
-Then, you can run Daphne and supply the channel layer as the argument:
+Then, you can run Daphne and supply the channel layer as the argument::
 
     daphne my_project.asgi:channel_layer
 
@@ -152,3 +152,26 @@ customise requests is run on the consumers.
 You can even use different Python versions for the interface servers and the
 workers; the ASGI protocol that channel layers communicate over
 is designed to be very portable and network-transparent.
+
+
+.. _wsgi-to-asgi:
+
+Running ASGI under WSGI
+-----------------------
+
+ASGI is a relatively new specification, and so it's backwards compatible with
+WSGI servers with an adapter layer. You won't get WebSocket support this way -
+WSGI doesn't support WebSockets - but you can run a separate ASGI server to
+handle WebSockets if you want.
+
+The ``wsgiref`` package contains the adapter; all you need to do is put this
+in your Django project's ``wsgi.py`` to declare a new WSGI application object
+that backs onto ASGI underneath::
+
+    import os
+    from asgiref.wsgi import WsgiToAsgiAdapter
+    from channels.asgi import get_channel_layer
+
+    os.environ.setdefault("DJANGO_SETTINGS_MODULE", "django_test.settings")
+    channel_layer = get_channel_layer()
+    application = WsgiToAsgiAdapter(channel_layer)

docs/getting-started.rst

@@ -127,6 +127,8 @@ Now, that's taken care of adding and removing WebSocket send channels for the
 we're not going to store a history of messages or anything and just replay
 any message sent in to all connected clients. Here's all the code::
 
+.. _websocket-example:
+
     # In consumers.py
     from channels import Group
 

docs/index.rst

@@ -15,6 +15,8 @@ data model underlying Channels and how they're used inside Django.
 Then, read :doc:`getting-started` to see how to get up and running with
 WebSockets with only 30 lines of code.
 
+If you want a quick overview, start with :doc:`inshort`.
+
 You can find the Channels repository `on GitHub <http://github.com/andrewgodwin/channels/>`_.
 
 Contents:
@@ -22,6 +24,7 @@ Contents:
 .. toctree::
    :maxdepth: 2
 
+   inshort
    concepts
    installation
    getting-started

docs/inshort.rst

@@ -0,0 +1,90 @@
+In Short
+========
+
+
+What is Channels?
+-----------------
+
+Channels extends Django to add :ref:`a new layer <what-are-channels>`
+that allows two important features:
+
+* WebSocket handling, in a way very :ref:`similar to normal views <websocket-example>`
+* Background tasks, running in the same servers as the rest of Django
+
+
+How?
+----
+
+It separates Django into two process types:
+
+* One that handles HTTP and WebSockets
+* One that runs views, websocket handlers and background tasks (*consumers*)
+
+They communicate via a protocol called :doc:`ASGI <asgi>`, which is similar
+to WSGI but runs over a network and allows for more protocol types.
+
+Channels does not introduce asyncio, gevent, or any other async code to
+your Django code; all of your business logic runs synchronously in a worker
+process or thread.
+
+
+I have to change how I run Django?
+----------------------------------
+
+No, all the new stuff is entirely optional. If you want it, however, you'll
+change from running Django under a WSGI server, to running:
+
+* An ASGI server, like `Daphne <http://github.com/andrewgodwin/daphne/>`
+* Django worker servers, using ``manage.py runworker``
+* Something to route ASGI requests over, like Redis or a database.
+
+
+What else does Channels give me?
+--------------------------------
+
+Other features include:
+
+* Easy HTTP long-poll support for thousands of clients at once
+* Full session and auth support for WebSockets
+* Automatic user login for WebSockets based on site cookies
+* Built-in primitives for mass triggering of events (chat, live blogs, etc.)
+* Zero-downtime deployment with browsers paused while new workers spin up
+* Optional low-level HTTP control on a per-URL basis
+* Extendability to other protocols or event sources (e.g. WebRTC, raw UDP, SMS)
+
+
+Does it scale?
+--------------
+
+Yes, you can run any number of *protocol servers* (ones that serve HTTP
+and WebSockets) and *worker servers* (ones that run your Django code) to
+fit your use case.
+
+The ASGI spec allows a number of different *channel layers* to be plugged in
+between these two components, with difference performance characteristics, and
+it's designed to allow both easy sharding as well as the ability to run
+separate clusters with their own protocol and worker servers.
+
+
+Do I need to worry about making all my code async-friendly?
+-----------------------------------------------------------
+
+No, all your code runs synchronously without any sockets or event loops to
+block. You can use async code within a Django view or channel consumer if you
+like - for example, to fetch lots of URLs in parallel - but it doesn't
+affect the overall deployed site.
+
+
+What version of Django does it work with?
+-----------------------------------------
+
+You can install Channels as a library for Django 1.8 and 1.9, and it (should be)
+part of Django 1.10. It has a few extra dependencies, but these will all
+be installed if you use `pip`.
+
+
+What do I read next?
+--------------------
+
+Start off by reading about the :doc:`concepts underlying Channels <concepts>`,
+and then move on to read our example-laden :doc:`Getting Started guide <getting-started>`.