Fix #4777: Add :async: option to py:function and py:method directives

CHANGES

@@ -78,8 +78,9 @@ Features added
 * #6212 autosummary: Add :confval:`autosummary_imported_members` to display
   imported members on autosummary
 * #6271: ``make clean`` is catastrophically broken if building into '.'
-* Add ``:classmethod:`` and ``:staticmethod:`` options to :rst:dir:`py:method`
-  directive
+* #4777: py domain: Add ``:async:`` option to :rst:dir:`py:function` directive
+* py domain: Add ``:async:``, ``:classmethod:`` and ``:staticmethod:`` options
+  to :rst:dir:`py:method` directive
 
 Bugs fixed
 ----------

doc/usage/restructuredtext/domains.rst

@@ -169,6 +169,13 @@ The following directives are provided for module and class contents:
    This information can (in any ``py`` directive) optionally be given in a
    structured form, see :ref:`info-field-lists`.
 
+   The ``async`` option can be given (with no value) to indicate the function is
+   an async method.
+
+   .. versionchanged:: 2.1
+
+      ``:async:`` option added.
+
 .. rst:directive:: .. py:data:: name
 
    Describes global data in a module, including both variables and values used
@@ -216,12 +223,15 @@ The following directives are provided for module and class contents:
    described for ``function``.  See also :ref:`signatures` and
    :ref:`info-field-lists`.
 
+   The ``async`` option can be given (with no value) to indicate the method is
+   an async method.
+
    The ``classmethod`` option and ``staticmethod`` option can be given (with
    no value) to indicate the method is a class method (or a static method).
 
    .. versionchanged:: 2.1
 
-      ``:classmethod:`` and ``:staticmethod:`` options added.
+      ``:async:``, ``:classmethod:`` and ``:staticmethod:`` options added.
 
 .. rst:directive:: .. py:staticmethod:: name(parameters)
 

sphinx/domains/python.py

@@ -438,6 +438,18 @@ class PyModulelevel(PyObject):
 class PyFunction(PyObject):
     """Description of a function."""
 
+    option_spec = PyObject.option_spec.copy()
+    option_spec.update({
+        'async': directives.flag,
+    })
+
+    def get_signature_prefix(self, sig):
+        # type: (str) -> str
+        if 'async' in self.options:
+            return 'async '
+        else:
+            return ''
+
     def needs_arglist(self):
         # type: () -> bool
         return True
@@ -573,6 +585,7 @@ class PyMethod(PyObject):
 
     option_spec = PyObject.option_spec.copy()
     option_spec.update({
+        'async': directives.flag,
         'classmethod': directives.flag,
         'staticmethod': directives.flag,
     })
@@ -583,10 +596,16 @@ class PyMethod(PyObject):
 
     def get_signature_prefix(self, sig):
         # type: (str) -> str
+        prefix = []
+        if 'async' in self.options:
+            prefix.append('async')
         if 'staticmethod' in self.options:
-            return 'static '
-        elif 'classmethod' in self.options:
-            return 'classmethod '
+            prefix.append('static')
+        if 'classmethod' in self.options:
+            prefix.append('classmethod')
+
+        if prefix:
+            return ' '.join(prefix) + ' '
         else:
             return ''
 

tests/test_domain_py.py

@@ -304,15 +304,24 @@ def test_pydata(app):
 
 
 def test_pyfunction(app):
-    text = ".. py:function:: func\n"
+    text = (".. py:function:: func1\n"
+            ".. py:function:: func2\n"
+            "   :async:\n")
     domain = app.env.get_domain('py')
     doctree = restructuredtext.parse(app, text)
     assert_node(doctree, (addnodes.index,
-                          [desc, ([desc_signature, ([desc_name, "func"],
+                          [desc, ([desc_signature, ([desc_name, "func1"],
+                                                    [desc_parameterlist, ()])],
+                                  [desc_content, ()])],
+                          addnodes.index,
+                          [desc, ([desc_signature, ([desc_annotation, "async "],
+                                                    [desc_name, "func2"],
                                                     [desc_parameterlist, ()])],
                                   [desc_content, ()])]))
-    assert 'func' in domain.objects
-    assert domain.objects['func'] == ('index', 'function')
+    assert 'func1' in domain.objects
+    assert domain.objects['func1'] == ('index', 'function')
+    assert 'func2' in domain.objects
+    assert domain.objects['func2'] == ('index', 'function')
 
 
 def test_pymethod_options(app):
@@ -322,7 +331,9 @@ def test_pymethod_options(app):
             "   .. py:method:: meth2\n"
             "      :classmethod:\n"
             "   .. py:method:: meth3\n"
-            "      :staticmethod:\n")
+            "      :staticmethod:\n"
+            "   .. py:method:: meth4\n"
+            "      :async:\n")
     domain = app.env.get_domain('py')
     doctree = restructuredtext.parse(app, text)
     assert_node(doctree, (addnodes.index,
@@ -333,6 +344,8 @@ def test_pymethod_options(app):
                                                   addnodes.index,
                                                   desc,
                                                   addnodes.index,
+                                                  desc,
+                                                  addnodes.index,
                                                   desc)])]))
 
     # method
@@ -364,6 +377,16 @@ def test_pymethod_options(app):
     assert 'Class.meth3' in domain.objects
     assert domain.objects['Class.meth3'] == ('index', 'method')
 
+    # :async:
+    assert_node(doctree[1][1][6], addnodes.index,
+                entries=[('single', 'meth4() (Class method)', 'Class.meth4', '', None)])
+    assert_node(doctree[1][1][7], ([desc_signature, ([desc_annotation, "async "],
+                                                     [desc_name, "meth4"],
+                                                     [desc_parameterlist, ()])],
+                                   [desc_content, ()]))
+    assert 'Class.meth4' in domain.objects
+    assert domain.objects['Class.meth4'] == ('index', 'method')
+
 
 def test_pyclassmethod(app):
     text = (".. py:class:: Class\n"