Close #7165: autodoc: Support Annotated type (PEP-593)

CHANGES

@@ -52,6 +52,7 @@ Features added
   not to document inherited members of the class and uppers
 * #6830: autodoc: consider a member private if docstring contains
   ``:meta private:`` in info-field-list
+* #7165: autodoc: Support Annotated type (PEP-593)
 * #6558: glossary: emit a warning for duplicated glossary entry
 * #3106: domain: Register hyperlink target for index page automatically
 * #6558: std domain: emit a warning for duplicated generic objects

sphinx/util/typing.py

@@ -49,7 +49,8 @@ def stringify(annotation: Any) -> str:
         return repr(annotation)
     elif annotation is NoneType:  # type: ignore
         return 'None'
-    elif getattr(annotation, '__module__', None) == 'builtins':
+    elif (getattr(annotation, '__module__', None) == 'builtins' and
+          hasattr(annotation, '__qualname__')):
         return annotation.__qualname__
     elif annotation is Ellipsis:
         return '...'
@@ -88,6 +89,8 @@ def _stringify_py37(annotation: Any) -> str:
             args = ', '.join(stringify(a) for a in annotation.__args__[:-1])
             returns = stringify(annotation.__args__[-1])
             return '%s[[%s], %s]' % (qualname, args, returns)
+        elif str(annotation).startswith('typing.Annotated'):  # for py39+
+            return stringify(annotation.__args__[0])
         elif annotation._special:
             return qualname
         else:

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

@@ -0,0 +1,6 @@
+from typing import Annotated
+
+
+def hello(name: Annotated[str, "attribute"]) -> None:
+    """docstring"""
+    pass

tests/test_autodoc.py

@@ -1524,6 +1524,24 @@ def test_autodoc_typed_instance_variables(app):
     ]
 
 
+@pytest.mark.skipif(sys.version_info < (3, 9), reason='py39+ is required.')
+@pytest.mark.sphinx('html', testroot='ext-autodoc')
+def test_autodoc_Annotated(app):
+    options = {"members": None}
+    actual = do_autodoc(app, 'module', 'target.annotated', options)
+    assert list(actual) == [
+        '',
+        '.. py:module:: target.annotated',
+        '',
+        '',
+        '.. py:function:: hello(name: str) -> None',
+        '   :module: target.annotated',
+        '',
+        '   docstring',
+        '   '
+    ]
+
+
 @pytest.mark.sphinx('html', testroot='pycode-egg')
 def test_autodoc_for_egged_code(app):
     options = {"members": None,

tests/test_util_typing.py

@@ -12,6 +12,8 @@ import sys
 from numbers import Integral
 from typing import Any, Dict, List, TypeVar, Union, Callable, Tuple, Optional
 
+import pytest
+
 from sphinx.util.typing import stringify
 
 
@@ -42,6 +44,12 @@ def test_stringify_type_hints_containers():
     assert stringify(List[Dict[str, Tuple]]) == "List[Dict[str, Tuple]]"
 
 
+@pytest.mark.skipif(sys.version_info < (3, 9), reason='python 3.9+ is required.')
+def test_stringify_Annotated():
+    from typing import Annotated
+    assert stringify(Annotated[str, "foo", "bar"]) == "str"
+
+
 def test_stringify_type_hints_string():
     assert stringify("int") == "int"
     assert stringify("str") == "str"