Merge branch '3.x' into 6857_enum_classmethod

CHANGES

@@ -74,6 +74,7 @@ Bugs fixed
 * #6588: autodoc: Decorated inherited method has no documentation
 * #7469: autodoc: The change of autodoc-process-docstring for variables is
   cached unexpectedly
+* #7559: autodoc: misdetects a sync function is async
 * #6857: autodoc: failed to detect a classmethod on Enum class
 * #7535: sphinx-autogen: crashes when custom template uses inheritance
 * #7536: sphinx-autogen: crashes when template uses i18n feature

doc/usage/extensions/doctest.rst

@@ -132,8 +132,8 @@ a comma-separated list of group names.
 
           .. testcode::
 
-             1+1        # this will give no output!
-             print 2+2  # this will give output
+             1+1         # this will give no output!
+             print(2+2)  # this will give output
 
           .. testoutput::
 
@@ -161,7 +161,7 @@ a comma-separated list of group names.
 
       .. testcode::
 
-         print 'Output     text.'
+         print('Output     text.')
 
       .. testoutput::
          :hide:
@@ -328,7 +328,7 @@ The doctest extension uses the following configuration values:
 
       Some documentation text.
 
-      >>> print 1
+      >>> print(1)
       1
 
       Some more documentation text.
@@ -344,7 +344,7 @@ The doctest extension uses the following configuration values:
 
       .. doctest::
 
-         >>> print 1
+         >>> print(1)
          1
 
       Some more documentation text.

sphinx/util/inspect.py

@@ -125,13 +125,15 @@ def unwrap(obj: Any) -> Any:
         return obj
 
 
-def unwrap_all(obj: Any) -> Any:
+def unwrap_all(obj: Any, *, stop: Callable = None) -> Any:
     """
     Get an original object from wrapped object (unwrapping partials, wrapped
     functions, and other decorators).
     """
     while True:
-        if ispartial(obj):
+        if stop and stop(obj):
+            return obj
+        elif ispartial(obj):
             obj = obj.func
         elif inspect.isroutine(obj) and hasattr(obj, '__wrapped__'):
             obj = obj.__wrapped__
@@ -287,7 +289,8 @@ def isroutine(obj: Any) -> bool:
 
 def iscoroutinefunction(obj: Any) -> bool:
     """Check if the object is coroutine-function."""
-    obj = unwrap_all(obj)
+    # unwrap staticmethod, classmethod and partial (except wrappers)
+    obj = unwrap_all(obj, stop=lambda o: hasattr(o, '__wrapped__'))
     if hasattr(obj, '__code__') and inspect.iscoroutinefunction(obj):
         # check obj.__code__ because iscoroutinefunction() crashes for custom method-like
         # objects (see https://github.com/sphinx-doc/sphinx/issues/6605)

tests/roots/test-ext-autodoc/target/coroutine.py

@@ -1,3 +1,7 @@
+import asyncio
+from functools import wraps
+
+
 class AsyncClass:
     async def do_coroutine(self):
         """A documented coroutine function"""
@@ -16,3 +20,14 @@ class AsyncClass:
 
 async def _other_coro_func():
     return "run"
+
+
+def myawait(f):
+    @wraps(f)
+    def wrapper(*args, **kwargs):
+        awaitable = f(*args, **kwargs)
+        return asyncio.run(awaitable)
+    return wrapper
+
+
+sync_func = myawait(_other_coro_func)

tests/test_autodoc.py

@@ -1380,6 +1380,15 @@ def test_coroutine():
         '',
     ]
 
+    # force-synchronized wrapper
+    actual = do_autodoc(app, 'function', 'target.coroutine.sync_func')
+    assert list(actual) == [
+        '',
+        '.. py:function:: sync_func()',
+        '   :module: target.coroutine',
+        '',
+    ]
+
 
 @pytest.mark.sphinx('html', testroot='ext-autodoc')
 def test_partialmethod(app):