Close #4777: autodoc: Support coroutine

CHANGES

@@ -75,6 +75,7 @@ Features added
   functions
 * #6289: autodoc: :confval:`autodoc_default_options` now supports
   ``imported-members`` option
+* #4777: autodoc: Support coroutine
 * #6212 autosummary: Add :confval:`autosummary_imported_members` to display
   imported members on autosummary
 * #6271: ``make clean`` is catastrophically broken if building into '.'

sphinx/ext/autodoc/__init__.py

@@ -1034,6 +1034,14 @@ class FunctionDocumenter(DocstringSignatureMixin, ModuleLevelDocumenter):  # typ
         # type: (bool) -> None
         pass
 
+    def add_directive_header(self, sig):
+        # type: (str) -> None
+        sourcename = self.get_sourcename()
+        super().add_directive_header(sig)
+
+        if inspect.iscoroutinefunction(self.object):
+            self.add_line('   :async:', sourcename)
+
 
 class DecoratorDocumenter(FunctionDocumenter):
     """
@@ -1318,9 +1326,11 @@ class MethodDocumenter(DocstringSignatureMixin, ClassLevelDocumenter):  # type:
 
         sourcename = self.get_sourcename()
         obj = self.parent.__dict__.get(self.object_name, self.object)
+        if inspect.iscoroutinefunction(obj):
+            self.add_line('   :async:', sourcename)
         if inspect.isclassmethod(obj):
             self.add_line('   :classmethod:', sourcename)
-        elif inspect.isstaticmethod(obj, cls=self.parent, name=self.object_name):
+        if inspect.isstaticmethod(obj, cls=self.parent, name=self.object_name):
             self.add_line('   :staticmethod:', sourcename)
 
     def document_members(self, all_members=False):

tests/test_autodoc.py

@@ -1523,6 +1523,15 @@ def test_bound_method():
 
 @pytest.mark.usefixtures('setup_test')
 def test_coroutine():
+    actual = do_autodoc(app, 'function', 'target.functions.coroutinefunc')
+    assert list(actual) == [
+        '',
+        '.. py:function:: coroutinefunc()',
+        '   :module: target.functions',
+        '   :async:',
+        '',
+    ]
+
     options = {"members": None}
     actual = do_autodoc(app, 'class', 'target.coroutine.AsyncClass', options)
     assert list(actual) == [
@@ -1533,6 +1542,7 @@ def test_coroutine():
         '   ',
         '   .. py:method:: AsyncClass.do_coroutine()',
         '      :module: target.coroutine',
+        '      :async:',
         '   ',
         '      A documented coroutine function',
         '      '