Merge pull request #10147 from zuqq/4.x

Apply `autodoc_typehints_format` to all type hints

CHANGES

@@ -70,6 +70,8 @@ Features added
 * #9792: autodoc: Add new option for ``autodoc_typehints_description_target`` to
   include undocumented return values but not undocumented parameters.
 * #10285: autodoc: singledispatch functions having typehints are not documented
+* autodoc: :confval:`autodoc_typehints_format` now also applies to attributes,
+  data, properties, and type variable bounds.
 * #10258: autosummary: Recognize a documented attribute of a module as
   non-imported
 * #10028: Removed internal usages of JavaScript frameworks (jQuery and

sphinx/ext/autodoc/__init__.py

@@ -1897,7 +1897,10 @@ class TypeVarMixin(DataDocumenterMixinBase):
         if isinstance(self.object, TypeVar):
             attrs = [repr(self.object.__name__)]
             for constraint in self.object.__constraints__:
-                attrs.append(stringify_typehint(constraint))
+                if self.config.autodoc_typehints_format == "short":
+                    attrs.append(stringify_typehint(constraint, "smart"))
+                else:
+                    attrs.append(stringify_typehint(constraint))
             if self.object.__bound__:
                 if self.config.autodoc_typehints_format == "short":
                     bound = restify(self.object.__bound__, "smart")
@@ -2019,7 +2022,11 @@ class DataDocumenter(GenericAliasMixin, NewTypeMixin, TypeVarMixin,
                 annotations = get_type_hints(self.parent, None,
                                              self.config.autodoc_type_aliases)
                 if self.objpath[-1] in annotations:
-                    objrepr = stringify_typehint(annotations.get(self.objpath[-1]))
+                    if self.config.autodoc_typehints_format == "short":
+                        objrepr = stringify_typehint(annotations.get(self.objpath[-1]),
+                                                     "smart")
+                    else:
+                        objrepr = stringify_typehint(annotations.get(self.objpath[-1]))
                     self.add_line('   :type: ' + objrepr, sourcename)
 
             try:
@@ -2619,7 +2626,11 @@ class AttributeDocumenter(GenericAliasMixin, NewTypeMixin, SlotsMixin,  # type:
                 annotations = get_type_hints(self.parent, None,
                                              self.config.autodoc_type_aliases)
                 if self.objpath[-1] in annotations:
-                    objrepr = stringify_typehint(annotations.get(self.objpath[-1]))
+                    if self.config.autodoc_typehints_format == "short":
+                        objrepr = stringify_typehint(annotations.get(self.objpath[-1]),
+                                                     "smart")
+                    else:
+                        objrepr = stringify_typehint(annotations.get(self.objpath[-1]))
                     self.add_line('   :type: ' + objrepr, sourcename)
 
             try:
@@ -2743,7 +2754,10 @@ class PropertyDocumenter(DocstringStripSignatureMixin, ClassLevelDocumenter):  #
                 signature = inspect.signature(func,
                                               type_aliases=self.config.autodoc_type_aliases)
                 if signature.return_annotation is not Parameter.empty:
-                    objrepr = stringify_typehint(signature.return_annotation)
+                    if self.config.autodoc_typehints_format == "short":
+                        objrepr = stringify_typehint(signature.return_annotation, "smart")
+                    else:
+                        objrepr = stringify_typehint(signature.return_annotation)
                     self.add_line('   :type: ' + objrepr, sourcename)
             except TypeError as exc:
                 logger.warning(__("Failed to get a function signature for %s: %s"),

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

@@ -1,7 +1,13 @@
-from typing import Any, Tuple, Union
+import pathlib
+from typing import Any, Tuple, TypeVar, Union
 
 CONST1: int
+#: docstring
 CONST2: int = 1
+#: docstring
+CONST3: pathlib.PurePosixPath = pathlib.PurePosixPath("/a/b/c")
+#: docstring
+T = TypeVar("T", bound=pathlib.PurePosixPath)
 
 
 def incr(a: int, b: int = 1) -> int:
@@ -16,6 +22,7 @@ def decr(a, b = 1):
 class Math:
     CONST1: int
     CONST2: int = 1
+    CONST3: pathlib.PurePosixPath = pathlib.PurePosixPath("/a/b/c")
 
     def __init__(self, s: str, o: Any = None) -> None:
         pass
@@ -42,6 +49,10 @@ class Math:
     def prop(self) -> int:
         return 0
 
+    @property
+    def path(self) -> pathlib.PurePosixPath:
+        return pathlib.PurePosixPath("/a/b/c")
+
 
 def tuple_args(x: Tuple[int, Union[int, str]]) -> Tuple[int, int]:
     pass

tests/test_ext_autodoc_configs.py

@@ -613,6 +613,22 @@ def test_autodoc_typehints_signature(app):
         '   :type: int',
         '',
         '',
+        '.. py:data:: CONST2',
+        '   :module: target.typehints',
+        '   :type: int',
+        '   :value: 1',
+        '',
+        '   docstring',
+        '',
+        '',
+        '.. py:data:: CONST3',
+        '   :module: target.typehints',
+        '   :type: ~pathlib.PurePosixPath',
+        "   :value: PurePosixPath('/a/b/c')",
+        '',
+        '   docstring',
+        '',
+        '',
         '.. py:class:: Math(s: str, o: %s = None)' % type_o,
         '   :module: target.typehints',
         '',
@@ -628,6 +644,12 @@ def test_autodoc_typehints_signature(app):
         '      :value: 1',
         '',
         '',
+        '   .. py:attribute:: Math.CONST3',
+        '      :module: target.typehints',
+        '      :type: ~pathlib.PurePosixPath',
+        "      :value: PurePosixPath('/a/b/c')",
+        '',
+        '',
         '   .. py:method:: Math.decr(a: int, b: int = 1) -> int',
         '      :module: target.typehints',
         '',
@@ -644,6 +666,11 @@ def test_autodoc_typehints_signature(app):
         '      :module: target.typehints',
         '',
         '',
+        '   .. py:property:: Math.path',
+        '      :module: target.typehints',
+        '      :type: ~pathlib.PurePosixPath',
+        '',
+        '',
         '   .. py:property:: Math.prop',
         '      :module: target.typehints',
         '      :type: int',
@@ -661,6 +688,14 @@ def test_autodoc_typehints_signature(app):
         '   :module: target.typehints',
         '',
         '',
+        '.. py:data:: T',
+        '   :module: target.typehints',
+        '',
+        '   docstring',
+        '',
+        "   alias of TypeVar('T', bound=\\ :py:class:`~pathlib.PurePosixPath`)",
+        '',
+        '',
         '.. py:function:: complex_func(arg1: str, arg2: List[int], arg3: Tuple[int, '
         'Union[str, Unknown]] = None, *args: str, **kwargs: str) -> None',
         '   :module: target.typehints',
@@ -700,6 +735,20 @@ def test_autodoc_typehints_none(app):
         '   :module: target.typehints',
         '',
         '',
+        '.. py:data:: CONST2',
+        '   :module: target.typehints',
+        '   :value: 1',
+        '',
+        '   docstring',
+        '',
+        '',
+        '.. py:data:: CONST3',
+        '   :module: target.typehints',
+        "   :value: PurePosixPath('/a/b/c')",
+        '',
+        '   docstring',
+        '',
+        '',
         '.. py:class:: Math(s, o=None)',
         '   :module: target.typehints',
         '',
@@ -713,6 +762,11 @@ def test_autodoc_typehints_none(app):
         '      :value: 1',
         '',
         '',
+        '   .. py:attribute:: Math.CONST3',
+        '      :module: target.typehints',
+        "      :value: PurePosixPath('/a/b/c')",
+        '',
+        '',
         '   .. py:method:: Math.decr(a, b=1)',
         '      :module: target.typehints',
         '',
@@ -729,6 +783,10 @@ def test_autodoc_typehints_none(app):
         '      :module: target.typehints',
         '',
         '',
+        '   .. py:property:: Math.path',
+        '      :module: target.typehints',
+        '',
+        '',
         '   .. py:property:: Math.prop',
         '      :module: target.typehints',
         '',
@@ -745,6 +803,14 @@ def test_autodoc_typehints_none(app):
         '   :module: target.typehints',
         '',
         '',
+        '.. py:data:: T',
+        '   :module: target.typehints',
+        '',
+        '   docstring',
+        '',
+        "   alias of TypeVar('T', bound=\\ :py:class:`~pathlib.PurePosixPath`)",
+        '',
+        '',
         '.. py:function:: complex_func(arg1, arg2, arg3=None, *args, **kwargs)',
         '   :module: target.typehints',
         '',
@@ -1153,7 +1219,7 @@ def test_autodoc_type_aliases(app):
         '',
         '.. py:data:: variable3',
         '   :module: target.autodoc_type_aliases',
-        '   :type: Optional[int]',
+        '   :type: ~typing.Optional[int]',
         '',
         '   docstring',
         '',
@@ -1224,7 +1290,7 @@ def test_autodoc_type_aliases(app):
         '',
         '.. py:data:: variable3',
         '   :module: target.autodoc_type_aliases',
-        '   :type: Optional[myint]',
+        '   :type: ~typing.Optional[myint]',
         '',
         '   docstring',
         '',
@@ -1274,6 +1340,22 @@ def test_autodoc_typehints_format_fully_qualified(app):
         '   :type: int',
         '',
         '',
+        '.. py:data:: CONST2',
+        '   :module: target.typehints',
+        '   :type: int',
+        '   :value: 1',
+        '',
+        '   docstring',
+        '',
+        '',
+        '.. py:data:: CONST3',
+        '   :module: target.typehints',
+        '   :type: pathlib.PurePosixPath',
+        "   :value: PurePosixPath('/a/b/c')",
+        '',
+        '   docstring',
+        '',
+        '',
         '.. py:class:: Math(s: str, o: %s = None)' % type_o,
         '   :module: target.typehints',
         '',
@@ -1289,6 +1371,12 @@ def test_autodoc_typehints_format_fully_qualified(app):
         '      :value: 1',
         '',
         '',
+        '   .. py:attribute:: Math.CONST3',
+        '      :module: target.typehints',
+        '      :type: pathlib.PurePosixPath',
+        "      :value: PurePosixPath('/a/b/c')",
+        '',
+        '',
         '   .. py:method:: Math.decr(a: int, b: int = 1) -> int',
         '      :module: target.typehints',
         '',
@@ -1305,6 +1393,11 @@ def test_autodoc_typehints_format_fully_qualified(app):
         '      :module: target.typehints',
         '',
         '',
+        '   .. py:property:: Math.path',
+        '      :module: target.typehints',
+        '      :type: pathlib.PurePosixPath',
+        '',
+        '',
         '   .. py:property:: Math.prop',
         '      :module: target.typehints',
         '      :type: int',
@@ -1322,6 +1415,14 @@ def test_autodoc_typehints_format_fully_qualified(app):
         '   :module: target.typehints',
         '',
         '',
+        '.. py:data:: T',
+        '   :module: target.typehints',
+        '',
+        '   docstring',
+        '',
+        "   alias of TypeVar('T', bound=\\ :py:class:`pathlib.PurePosixPath`)",
+        '',
+        '',
         '.. py:function:: complex_func(arg1: str, arg2: List[int], arg3: Tuple[int, '
         'Union[str, Unknown]] = None, *args: str, **kwargs: str) -> None',
         '   :module: target.typehints',