Merge pull request #348 from KeepSafe/coroutine_docs

Add sphinx extension for coroutinemethod and coroutinefunction markup

docs/aiohttp_doctools.py

@@ -0,0 +1,27 @@
+from sphinx.domains.python import PyModulelevel, PyClassmember
+from sphinx import addnodes
+
+
+class PyCoroutineMixin(object):
+    def handle_signature(self, sig, signode):
+        ret = super(PyCoroutineMixin, self).handle_signature(sig, signode)
+        signode.insert(0, addnodes.desc_annotation('coroutine ', 'coroutine '))
+        return ret
+
+
+class PyCoroutineFunction(PyCoroutineMixin, PyModulelevel):
+    def run(self):
+        self.name = 'py:function'
+        return PyModulelevel.run(self)
+
+
+class PyCoroutineMethod(PyCoroutineMixin, PyClassmember):
+    def run(self):
+        self.name = 'py:method'
+        return PyClassmember.run(self)
+
+
+def setup(app):
+    app.add_directive_to_domain('py', 'coroutinefunction', PyCoroutineFunction)
+    app.add_directive_to_domain('py', 'coroutinemethod', PyCoroutineMethod)
+    return {'version': '1.0', 'parallel_read_safe': True}

docs/client_websockets.rst

@@ -87,11 +87,11 @@ do not create an instance of class :class:`ClientWebSocketResponse` manually.
 
       May be ``None`` if server and client protocols are
       not overlapping.
-      
+
    .. method:: exception()
 
       Returns exception if any occurs or returns None.
-      
+
    .. method:: ping(message=b'')
 
       Send :const:`~aiohttp.websocket.MSG_PING` to peer.
@@ -117,7 +117,7 @@ do not create an instance of class :class:`ClientWebSocketResponse` manually.
       :raise TypeError: if data is not :class:`bytes`,
                         :class:`bytearray` or :class:`memoryview`.
 
-   .. method:: close(*, code=1000, message=b'')
+   .. coroutinemethod:: close(*, code=1000, message=b'')
 
       A :ref:`coroutine<coroutine>` that initiates closing handshake by sending
       :const:`~aiohttp.websocket.MSG_CLOSE` message. It waits for
@@ -130,7 +130,7 @@ do not create an instance of class :class:`ClientWebSocketResponse` manually.
                       :class:`str` (converted to *UTF-8* encoded bytes)
                       or :class:`bytes`.
 
-   .. method:: receive()
+   .. coroutinemethod:: receive()
 
       A :ref:`coroutine<coroutine>` that waits upcoming *data*
       message from peer and returns it.

docs/conf.py

@@ -37,6 +37,7 @@
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 sys.path.insert(0, os.path.abspath('..'))
+sys.path.insert(0, os.path.abspath('.'))
 
 import alabaster
 
@@ -53,6 +54,7 @@
     'sphinx.ext.viewcode',
     'sphinx.ext.intersphinx',
     'alabaster',
+    'aiohttp_doctools',
 ]
 
 intersphinx_mapping = {

docs/web_reference.rst

@@ -180,32 +180,28 @@ first positional parameter.
 
       Returns :class:`int` or ``None`` if *Content-Length* is absent.
 
-   .. method:: read()
+   .. coroutinemethod:: read()
 
       Read request body, returns :class:`bytes` object with body content.
 
-      The method is a :ref:`coroutine <coroutine>`.
-
       .. note::
 
          The method **does** store read data internally, subsequent
          :meth:`~Request.read` call will return the same value.
 
-   .. method:: text()
+   .. coroutinemethod:: text()
 
       Read request body, decode it using :attr:`charset` encoding or
       ``UTF-8`` if no encoding was specified in *MIME-type*.
 
       Returns :class:`str` with body content.
 
-      The method is a :ref:`coroutine <coroutine>`.
-
       .. note::
 
          The method **does** store read data internally, subsequent
          :meth:`~Request.text` call will return the same value.
 
-   .. method:: json(*, loader=json.loads)
+   .. coroutinemethod:: json(*, loader=json.loads)
 
       Read request body decoded as *json*.
 
@@ -227,7 +223,7 @@ first positional parameter.
          The method **does** store read data internally, subsequent
          :meth:`~Request.json` call will return the same value.
 
-   .. method:: post()
+   .. coroutinemethod:: post()
 
       A :ref:`coroutine <coroutine>` that reads POST parameters from
       request body.
@@ -245,14 +241,12 @@ first positional parameter.
          The method **does** store read data internally, subsequent
          :meth:`~Request.post` call will return the same value.
 
-   .. method:: release()
+   .. coroutinemethod:: release()
 
       Release request.
 
       Eat unread part of HTTP BODY if present.
 
-      The method is a :ref:`coroutine <coroutine>`.
-
       .. note::
 
           User code may never call :meth:`~Request.release`, all
@@ -512,7 +506,7 @@ StreamResponse
 
       Raises :exc:`RuntimeError` if :meth:`write_eof` has been called.
 
-   .. method:: drain()
+   .. coroutinemethod:: drain()
 
       A :ref:`coroutine<coroutine>` to let the write buffer of the
       underlying transport a chance to be flushed.
@@ -530,7 +524,7 @@ StreamResponse
 
       .. versionadded:: 0.14
 
-   .. method:: write_eof()
+   .. coroutinemethod:: write_eof()
 
       A :ref:`coroutine<coroutine>` *may* be called as a mark of the
       *HTTP response* processing finish.
@@ -695,9 +689,9 @@ WebSocketResponse
       :raise TypeError: if data is not :class:`bytes`,
                         :class:`bytearray` or :class:`memoryview`.
 
-   .. method:: close(*, code=1000, message=b'')
+   .. coroutinemethod:: close(*, code=1000, message=b'')
 
-      A :ref:`coroutine<coroutine>` that initiates closing 
+      A :ref:`coroutine<coroutine>` that initiates closing
       handshake by sending :const:`~aiohttp.websocket.MSG_CLOSE` message.
 
       :param int code: closing code
@@ -708,7 +702,7 @@ WebSocketResponse
 
       :raise RuntimeError: if connection is not started or closing
 
-   .. method:: receive()
+   .. coroutinemethod:: receive()
 
       A :ref:`coroutine<coroutine>` that waits upcoming *data*
       message from peer and returns it.
@@ -731,7 +725,7 @@ WebSocketResponse
 
       :raise: :exc:`~aiohttp.errors.WSClientDisconnectedError` on closing.
 
-   .. method:: receive_str()
+   .. coroutinemethod:: receive_str()
 
       A :ref:`coroutine<coroutine>` that calls :meth:`receive_mgs` but
       also asserts the message type is
@@ -741,7 +735,7 @@ WebSocketResponse
 
       :raise TypeError: if message is :const:`~aiohttp.websocket.MSG_BINARY`.
 
-   .. method:: receive_bytes()
+   .. coroutinemethod:: receive_bytes()
 
       A :ref:`coroutine<coroutine>` that calls :meth:`receive_mgs` but
       also asserts the message type is
@@ -845,7 +839,7 @@ arbitrary properties for later access from
          yield from loop.create_server(app.make_handler(),
                                        '0.0.0.0', 8080)
 
-   .. method:: finish()
+   .. coroutinemethod:: finish()
 
       A :ref:`coroutine<coroutine>` that should be called after
       server stopping.
@@ -988,7 +982,7 @@ Router is any object that implements :class:`AbstractRouter` interface.
 
    :returns: new :class:`StaticRoute` instance.
 
-   .. method:: resolve(requst)
+   .. coroutinemethod:: resolve(requst)
 
       A :ref:`coroutine<coroutine>` that returns
       :class:`AbstractMatchInfo` for *request*.