Update documentation to async code (capnproto#331)

This commit updates the documentation to the latest changes added
with pycapnp 2.0.0.

* Remove non existing classes/functions from the reference documentation
* Adapt the quickstart to the latest changes. Mainly to new rpc handling,
  that now exlusively is done through asyncio.

README.md

@@ -77,7 +77,7 @@ While not directly supported by pycapnp, a tool has been created to help generat
 
 ## Python Versions
 
-Python 3.7+ is supported.
+Python 3.8+ is supported.
 
 
 ## Development

capnp/lib/capnp.pyx

@@ -438,8 +438,10 @@ cdef class _DynamicListReader:
 cdef class _DynamicResizableListBuilder:
     """Class for building growable Cap'n Proto Lists
 
-    .. warning:: You need to call :meth:`finish` on this object before serializing the Cap'n Proto message.
-    Failure to do so will cause your objects not to be written out as well as leaking orphan structs into your message.
+    .. warning::
+        You need to call :meth:`finish` on this object before serializing the
+        Cap'n Proto message. Failure to do so will cause your objects not to be
+        written out as well as leaking orphan structs into your message.
 
     This class works much like :class:`_DynamicListBuilder`, but it allows growing the list dynamically.
     It is meant for lists of structs, since for primitive types like int or float, you're much better off
@@ -1436,9 +1438,11 @@ cdef class _DynamicStructBuilder:
         This is only meant for lists of Cap'n Proto objects, since for primitive types
         you can just define a normal python list and fill it yourself.
 
-        .. warning:: You need to call :meth:`_DynamicResizableListBuilder.finish` on the
-        list object before serializing the Cap'n Proto message. Failure to do so will cause
-        your objects not to be written out as well as leaking orphan structs into your message.
+        .. warning::
+            You need to call :meth:`_DynamicResizableListBuilder.finish` on the
+            list object before serializing the Cap'n Proto message. Failure to do
+            so will cause your objects not to be written out as well as leaking
+            orphan structs into your message.
 
         :type field: str
         :param field: The field name to initialize
@@ -1850,6 +1854,16 @@ cdef class _EventLoop:
 
 @_asynccontextmanager
 async def kj_loop():
+    """Context manager for running the KJ event loop
+
+    As long as the context manager is active it is guaranteed that the KJ event
+    loop is running. When the context manager is exited, the KJ event loop is
+    shut down properly and pending tasks are cancelled.
+
+    :raises [RuntimeError]: If the KJ event loop is already running (on this thread).
+
+    .. warning:: Every capnp rpc call required a running KJ event loop.
+    """
     asyncio_loop = asyncio.get_running_loop()
     if hasattr(asyncio_loop, '_kj_loop'):
         raise RuntimeError("The KJ event-loop is already running (on this thread).")
@@ -1876,6 +1890,12 @@ async def kj_loop():
         kj_loop.close()
 
 async def run(coro):
+    """Ensure that the coroutine runs while the KJ event loop is running
+    
+    This is a shortcut for wrapping the coroutine in a :py:meth:`capnp.kj_loop` context manager.
+
+    :param coro: Coroutine to run
+    """
     async with kj_loop():
         return await coro
 
@@ -4391,7 +4411,7 @@ def add_import_hook(additional_paths=[]):
 
     :type additional_paths: list
     :param additional_paths: Additional paths, listed as strings, to be used to search for the .capnp files.
-    It is prepended to the beginning of sys.path. It also affects imports inside of Cap'n Proto schemas.
+        It is prepended to the beginning of sys.path. It also affects imports inside of Cap'n Proto schemas.
     """
     global _importer
     if _importer is not None:

docs/capnp.rst

@@ -14,50 +14,34 @@ Classes
 RPC
 ~~~
 
-Promise
-#######
-
-.. autoclass:: Promise
+.. autoclass:: capnp.lib.capnp._RemotePromise
   :members:
   :undoc-members:
   :inherited-members:
 
-Promise may be one of:
-
-* :meth:`capnp.lib.capnp._Promise`
-* :meth:`capnp.lib.capnp._RemotePromise`
-* :meth:`capnp.lib.capnp._VoidPromise`
-
-.. autoclass:: capnp.lib.capnp._Promise
-  :members:
-  :undoc-members:
-  :inherited-members:
+Communication
+#############
 
-.. autoclass:: capnp.lib.capnp._RemotePromise
+.. autoclass:: TwoPartyClient
   :members:
   :undoc-members:
   :inherited-members:
 
-.. autoclass:: capnp.lib.capnp._VoidPromise
+.. autoclass:: TwoPartyServer
   :members:
   :undoc-members:
   :inherited-members:
 
-
-Communication
-#############
-
-.. autoclass:: TwoPartyClient
+.. autoclass:: AsyncIoStream
   :members:
   :undoc-members:
   :inherited-members:
 
-.. autoclass:: TwoPartyServer
+.. autoclass:: capnp.lib.capnp._AsyncIoStream
   :members:
   :undoc-members:
   :inherited-members:
 
-
 Capability
 ##########
 
@@ -96,16 +80,14 @@ Miscellaneous
 Functions
 ---------
 .. autofunction:: add_import_hook
+.. autofunction:: remove_import_hook
 .. autofunction:: cleanup_global_schema_parser
-.. autofunction:: create_event_loop
-.. autofunction:: getTimer
-.. autofunction:: join_promises
+
+.. autofunction:: kj_loop
+.. autofunction:: run
+
 .. autofunction:: load
-.. autofunction:: poll_once
-.. autofunction:: remove_event_loop
-.. autofunction:: remove_import_hook
-.. autofunction:: reset_event_loop
-.. autofunction:: wait_forever
+
 
 
 Internal Classes

docs/conf.py

@@ -307,6 +307,6 @@
 # Allow duplicate toc entries.
 # epub_tocdup = True
 
-intersphinx_mapping = {"http://docs.python.org/": None}
+intersphinx_mapping = {"<name>": ("http://docs.python.org/", None)}
 
 smv_branch_whitelist = r"^master$"