Add initial documentation on asyncio support

docs/asyncio.rst

@@ -0,0 +1,69 @@
+Asyncio support
+===============
+
+The library has full support of asyncio, though you need to be aware it has some limitations.
+
+Example
+-------
+
+A very basic example on how to do raw API call:
+
+.. code-block:: python
+
+    import asyncio
+    from grapheneapi.aio.websocket import Websocket
+
+    import logging
+    logger = logging.getLogger('websockets')
+    logger.setLevel(logging.DEBUG)
+    logger.addHandler(logging.StreamHandler())
+
+    loop = asyncio.get_event_loop()
+    ws = Websocket('wss://eu.nodes.bitshares.ws', loop=loop)
+    props = loop.run_until_complete(ws.get_dynamic_global_properties())
+    print(props)
+
+Limitations
+-----------
+
+* Most of the classes requires async init because during instantiation some API calls has to be performed:
+
+.. code-block:: python
+
+    await Amount('10 FOO')
+
+* Several math operations are not available for :class:`graphenecommon.aio.Amount`, :class:`graphenecommon.aio.Price`
+  objects. This includes multiplication, division etc. This limitation is due to unability to define python magic
+  methods (``__mul__``, ``__div__``, etc) as async coroutines
+
+Concurrent RPC calls
+--------------------
+
+When using async version, you can perform multiple RPC calls from different coroutines concurrently. The library will
+send requests immediately in non-blocking manner. Incoming responses will be properly matched with queries by using "id"
+field of json-rpc query.
+
+Subscriptions
+-------------
+
+In asyncio version subscription notifications are not handled in callback-based manner. Instead, they are available in
+`self.notifications` queue which is :class:`asyncio.Queue`.
+
+Debugging
+---------
+
+To enable debugging on RPC level, you can raise loglevel on following loggers (don't forget to set formatter as well):
+
+.. code-block:: python
+
+    log = logging.getLogger("websockets")
+    log.setLevel(logging.DEBUG)
+
+    log = logging.getLogger("grapheneapi")
+    log.setLevel(logging.DEBUG)
+
+Tests
+-----
+
+Current testsuite uses pre-populated object cache, so it doesn't cover lots of functionality. Asyncio-specific tests
+could be run via ``pytest -v tests/test_*aio*.py``

docs/index.rst

@@ -35,6 +35,7 @@ Python-Graphene Libraries
 
    installation
    classes
+   asyncio
 
 Graphene API
 ------------