autodoc: The default of autodoc_typehints_format becomes to 'smart'

The default value of autodoc_typehints_format configuration is changed
to `'smart'`.  It will suppress the leading module names of typehints
(ex. `io.StringIO` -> `StringIO`).

refs: sphinx-doc#9075

CHANGES

@@ -30,6 +30,10 @@ Deprecated
 Features added
 --------------
 
+* #9075: autodoc: The default value of :confval:`autodoc_typehints_format` is
+  changed to ``'smart'``.  It will suppress the leading module names of
+  typehints (ex. ``io.StringIO`` -> ``StringIO``).
+
 Bugs fixed
 ----------
 

doc/usage/extensions/autodoc.rst

@@ -668,12 +668,15 @@ There are also config values that you can set:
    following values:
 
    * ``'fully-qualified'`` -- Show the module name and its name of typehints
-     (default)
    * ``'short'`` -- Suppress the leading module names of the typehints
-     (ex. ``io.StringIO`` -> ``StringIO``)
+     (ex. ``io.StringIO`` -> ``StringIO``)  (default)
 
    .. versionadded:: 4.4
 
+   .. versionchanged:: 5.0
+
+      The default setting was changed to ``'short'``
+
 .. confval:: autodoc_preserve_defaults
 
    If True, the default argument values of functions will be not evaluated on

sphinx/ext/autodoc/__init__.py

@@ -2871,7 +2871,7 @@ def setup(app: Sphinx) -> Dict[str, Any]:
     app.add_config_value('autodoc_typehints_description_target', 'all', True,
                          ENUM('all', 'documented'))
     app.add_config_value('autodoc_type_aliases', {}, True)
-    app.add_config_value('autodoc_typehints_format', "fully-qualified", 'env',
+    app.add_config_value('autodoc_typehints_format', "short", 'env',
                          ENUM("fully-qualified", "short"))
     app.add_config_value('autodoc_warningiserror', True, True)
     app.add_config_value('autodoc_inherit_docstrings', True, True)

tests/test_ext_autodoc.py

@@ -1009,7 +1009,7 @@ def test_autodoc_inner_class(app):
         '',
         '.. py:class:: InnerChild()',
         '   :module: target', '',
-        '   Bases: :py:class:`target.Outer.Inner`',
+        '   Bases: :py:class:`~target.Outer.Inner`',
         '',
         '   InnerChild docstring',
         '',
@@ -1705,7 +1705,7 @@ def test_autodoc_typed_instance_variables(app):
         '.. py:attribute:: Alias',
         '   :module: target.typed_vars',
         '',
-        '   alias of :py:class:`target.typed_vars.Derived`',
+        '   alias of :py:class:`~target.typed_vars.Derived`',
         '',
         '.. py:class:: Class()',
         '   :module: target.typed_vars',
@@ -1910,7 +1910,7 @@ def test_autodoc_GenericAlias(app):
             '   A list of Class',
             '',
             '   alias of :py:class:`~typing.List`\\ '
-            '[:py:class:`target.genericalias.Class`]',
+            '[:py:class:`~target.genericalias.Class`]',
             '',
             '',
             '.. py:data:: T',
@@ -1950,7 +1950,7 @@ def test_autodoc_TypeVar(app):
         '',
         '      T6',
         '',
-        '      alias of :py:class:`datetime.date`',
+        '      alias of :py:class:`~datetime.date`',
         '',
         '',
         '.. py:data:: T1',
@@ -1990,7 +1990,7 @@ def test_autodoc_TypeVar(app):
         '',
         '   T6',
         '',
-        '   alias of :py:class:`datetime.date`',
+        '   alias of :py:class:`~datetime.date`',
         '',
         '',
         '.. py:data:: T7',
@@ -2322,7 +2322,7 @@ def test_autodoc(app, status, warning):
 
 my_name
 
-alias of bug2437.autodoc_dummy_foo.Foo"""
+alias of Foo"""
     assert warning.getvalue() == ''
 
 

tests/test_ext_autodoc_autoattribute.py

@@ -183,7 +183,7 @@ def test_autoattribute_NewType(app):
         '',
         '   T6',
         '',
-        '   alias of :py:class:`datetime.date`',
+        '   alias of :py:class:`~datetime.date`',
         '',
     ]
 

tests/test_ext_autodoc_autoclass.py

@@ -284,7 +284,7 @@ def test_show_inheritance_for_decendants_of_generic_type(app):
         '.. py:class:: Corge(iterable=(), /)',
         '   :module: target.classes',
         '',
-        '   Bases: :py:class:`target.classes.Quux`',
+        '   Bases: :py:class:`~target.classes.Quux`',
         '',
     ]
 
@@ -391,7 +391,7 @@ def autodoc_process_docstring(*args):
         '.. py:attribute:: Alias',
         '   :module: target.classes',
         '',
-        '   alias of :py:class:`target.classes.Foo`',
+        '   alias of :py:class:`~target.classes.Foo`',
     ]
 
 

tests/test_ext_autodoc_autodata.py

@@ -111,7 +111,7 @@ def test_autodata_NewType(app):
         '',
         '   T6',
         '',
-        '   alias of :py:class:`datetime.date`',
+        '   alias of :py:class:`~datetime.date`',
         '',
     ]
 

tests/test_ext_autodoc_autofunction.py

@@ -162,7 +162,7 @@ def test_wrapped_function_contextmanager(app):
     actual = do_autodoc(app, 'function', 'target.wrappedfunction.feeling_good')
     assert list(actual) == [
         '',
-        '.. py:function:: feeling_good(x: int, y: int) -> typing.Generator',
+        '.. py:function:: feeling_good(x: int, y: int) -> ~typing.Generator',
         '   :module: target.wrappedfunction',
         '',
         "   You'll feel better in this context!",

tests/test_ext_autodoc_automodule.py

@@ -130,4 +130,4 @@ def test_subclass_of_mocked_object(app):
 
     options = {'members': None}
     actual = do_autodoc(app, 'module', 'target.need_mocks', options)
-    assert '.. py:class:: Inherited(*args: typing.Any, **kwargs: typing.Any)' in actual
+    assert '.. py:class:: Inherited(*args: ~typing.Any, **kwargs: ~typing.Any)' in actual

tests/test_ext_autodoc_configs.py

@@ -612,7 +612,7 @@ def test_autodoc_typehints_signature(app):
         '   :type: int',
         '',
         '',
-        '.. py:class:: Math(s: str, o: typing.Optional[typing.Any] = None)',
+        '.. py:class:: Math(s: str, o: ~typing.Optional[~typing.Any] = None)',
         '   :module: target.typehints',
         '',
         '',
@@ -677,8 +677,8 @@ def test_autodoc_typehints_signature(app):
         '   :module: target.typehints',
         '',
         '',
-        '.. py:function:: tuple_args(x: typing.Tuple[int, typing.Union[int, str]]) '
-        '-> typing.Tuple[int, int]',
+        '.. py:function:: tuple_args(x: ~typing.Tuple[int, ~typing.Union[int, str]]) '
+        '-> ~typing.Tuple[int, int]',
         '   :module: target.typehints',
         '',
     ]
@@ -1028,7 +1028,7 @@ def test_autodoc_type_aliases(app):
         '   docstring',
         '',
         '',
-        '.. py:function:: read(r: _io.BytesIO) -> _io.StringIO',
+        '.. py:function:: read(r: ~_io.BytesIO) -> ~_io.StringIO',
         '   :module: target.autodoc_type_aliases',
         '',
         '   docstring',
@@ -1092,7 +1092,7 @@ def test_autodoc_type_aliases(app):
         '   docstring',
         '',
         '',
-        '.. py:function:: read(r: _io.BytesIO) -> my.module.StringIO',
+        '.. py:function:: read(r: ~_io.BytesIO) -> my.module.StringIO',
         '   :module: target.autodoc_type_aliases',
         '',
         '   docstring',
@@ -1144,8 +1144,8 @@ def test_autodoc_typehints_description_and_type_aliases(app):
 
 
 @pytest.mark.sphinx('html', testroot='ext-autodoc',
-                    confoverrides={'autodoc_typehints_format': "short"})
-def test_autodoc_typehints_format_short(app):
+                    confoverrides={'autodoc_typehints_format': "fully-qualified"})
+def test_autodoc_typehints_format_fully_qualified(app):
     options = {"members": None,
                "undoc-members": None}
     actual = do_autodoc(app, 'module', 'target.typehints', options)
@@ -1159,7 +1159,7 @@ def test_autodoc_typehints_format_short(app):
         '   :type: int',
         '',
         '',
-        '.. py:class:: Math(s: str, o: ~typing.Optional[~typing.Any] = None)',
+        '.. py:class:: Math(s: str, o: typing.Optional[typing.Any] = None)',
         '   :module: target.typehints',
         '',
         '',
@@ -1224,29 +1224,29 @@ def test_autodoc_typehints_format_short(app):
         '   :module: target.typehints',
         '',
         '',
-        '.. py:function:: tuple_args(x: ~typing.Tuple[int, ~typing.Union[int, str]]) '
-        '-> ~typing.Tuple[int, int]',
+        '.. py:function:: tuple_args(x: typing.Tuple[int, typing.Union[int, str]]) '
+        '-> typing.Tuple[int, int]',
         '   :module: target.typehints',
         '',
     ]
 
 
 @pytest.mark.sphinx('html', testroot='ext-autodoc',
-                    confoverrides={'autodoc_typehints_format': "short"})
-def test_autodoc_typehints_format_short_for_class_alias(app):
+                    confoverrides={'autodoc_typehints_format': "fully-qualified"})
+def test_autodoc_typehints_format_fully_qualified_for_class_alias(app):
     actual = do_autodoc(app, 'class', 'target.classes.Alias')
     assert list(actual) == [
         '',
         '.. py:attribute:: Alias',
         '   :module: target.classes',
         '',
-        '   alias of :py:class:`~target.classes.Foo`',
+        '   alias of :py:class:`target.classes.Foo`',
     ]
 
 
 @pytest.mark.sphinx('html', testroot='ext-autodoc',
-                    confoverrides={'autodoc_typehints_format': "short"})
-def test_autodoc_typehints_format_short_for_generic_alias(app):
+                    confoverrides={'autodoc_typehints_format': "fully-qualified"})
+def test_autodoc_typehints_format_fully_qualified_for_generic_alias(app):
     actual = do_autodoc(app, 'data', 'target.genericalias.L')
     if sys.version_info < (3, 7):
         assert list(actual) == [
@@ -1266,14 +1266,14 @@ def test_autodoc_typehints_format_short_for_generic_alias(app):
             '',
             '   A list of Class',
             '',
-            '   alias of :py:class:`~typing.List`\\ [:py:class:`~target.genericalias.Class`]',
+            '   alias of :py:class:`~typing.List`\\ [:py:class:`target.genericalias.Class`]',
             '',
         ]
 
 
 @pytest.mark.sphinx('html', testroot='ext-autodoc',
-                    confoverrides={'autodoc_typehints_format': "short"})
-def test_autodoc_typehints_format_short_for_newtype_alias(app):
+                    confoverrides={'autodoc_typehints_format': "fully-qualified"})
+def test_autodoc_typehints_format_fully_qualified_for_newtype_alias(app):
     actual = do_autodoc(app, 'data', 'target.typevar.T6')
     assert list(actual) == [
         '',
@@ -1282,7 +1282,7 @@ def test_autodoc_typehints_format_short_for_newtype_alias(app):
         '',
         '   T6',
         '',
-        '   alias of :py:class:`~datetime.date`',
+        '   alias of :py:class:`datetime.date`',
         '',
     ]
 

tests/test_ext_autodoc_preserve_defaults.py

@@ -36,15 +36,15 @@ def test_preserve_defaults(app):
         '   docstring',
         '',
         '',
-        '   .. py:method:: Class.meth(name: str = CONSTANT, sentinel: typing.Any = '
-        'SENTINEL, now: datetime.datetime = datetime.now(), color: int = %s) -> None' % color,
+        '   .. py:method:: Class.meth(name: str = CONSTANT, sentinel: ~typing.Any = '
+        'SENTINEL, now: ~datetime.datetime = datetime.now(), color: int = %s) -> None' % color,
         '      :module: target.preserve_defaults',
         '',
         '      docstring',
         '',
         '',
-        '.. py:function:: foo(name: str = CONSTANT, sentinel: typing.Any = SENTINEL, '
-        'now: datetime.datetime = datetime.now(), color: int = %s) -> None' % color,
+        '.. py:function:: foo(name: str = CONSTANT, sentinel: ~typing.Any = SENTINEL, '
+        'now: ~datetime.datetime = datetime.now(), color: int = %s) -> None' % color,
         '   :module: target.preserve_defaults',
         '',
         '   docstring',