From 616f112e6ad615977428af60fb035c9aba449d45 Mon Sep 17 00:00:00 2001 From: Takeshi KOMIYA Date: Sat, 1 Jan 2022 19:37:42 +0900 Subject: [PATCH] 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: #9075 --- CHANGES | 4 +++ doc/usage/extensions/autodoc.rst | 7 ++-- sphinx/ext/autodoc/__init__.py | 2 +- tests/test_ext_autodoc.py | 12 +++---- tests/test_ext_autodoc_autoattribute.py | 2 +- tests/test_ext_autodoc_autoclass.py | 4 +-- tests/test_ext_autodoc_autodata.py | 2 +- tests/test_ext_autodoc_autofunction.py | 2 +- tests/test_ext_autodoc_automodule.py | 2 +- tests/test_ext_autodoc_configs.py | 38 ++++++++++----------- tests/test_ext_autodoc_preserve_defaults.py | 8 ++--- 11 files changed, 45 insertions(+), 38 deletions(-) diff --git a/CHANGES b/CHANGES index 9c61a8b96d1..68978f99961 100644 --- a/CHANGES +++ b/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 ---------- diff --git a/doc/usage/extensions/autodoc.rst b/doc/usage/extensions/autodoc.rst index df588e91d41..506d209057c 100644 --- a/doc/usage/extensions/autodoc.rst +++ b/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 diff --git a/sphinx/ext/autodoc/__init__.py b/sphinx/ext/autodoc/__init__.py index 8a86f05b1af..718c40c30ba 100644 --- a/sphinx/ext/autodoc/__init__.py +++ b/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) diff --git a/tests/test_ext_autodoc.py b/tests/test_ext_autodoc.py index 62bbf83d0f2..35a507f77f6 100644 --- a/tests/test_ext_autodoc.py +++ b/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() == '' diff --git a/tests/test_ext_autodoc_autoattribute.py b/tests/test_ext_autodoc_autoattribute.py index 9502b3c5220..689da44e658 100644 --- a/tests/test_ext_autodoc_autoattribute.py +++ b/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`', '', ] diff --git a/tests/test_ext_autodoc_autoclass.py b/tests/test_ext_autodoc_autoclass.py index e68c72a586a..585dcaae1cb 100644 --- a/tests/test_ext_autodoc_autoclass.py +++ b/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`', ] diff --git a/tests/test_ext_autodoc_autodata.py b/tests/test_ext_autodoc_autodata.py index 9fbfaaf39df..045adeeb215 100644 --- a/tests/test_ext_autodoc_autodata.py +++ b/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`', '', ] diff --git a/tests/test_ext_autodoc_autofunction.py b/tests/test_ext_autodoc_autofunction.py index 6489626d2fc..c97be35c90f 100644 --- a/tests/test_ext_autodoc_autofunction.py +++ b/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!", diff --git a/tests/test_ext_autodoc_automodule.py b/tests/test_ext_autodoc_automodule.py index 05a73ac8179..f3377f6e668 100644 --- a/tests/test_ext_autodoc_automodule.py +++ b/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 diff --git a/tests/test_ext_autodoc_configs.py b/tests/test_ext_autodoc_configs.py index e84e360e899..122a260be5a 100644 --- a/tests/test_ext_autodoc_configs.py +++ b/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`', '', ] diff --git a/tests/test_ext_autodoc_preserve_defaults.py b/tests/test_ext_autodoc_preserve_defaults.py index a7a24e026a9..411cbf6bf76 100644 --- a/tests/test_ext_autodoc_preserve_defaults.py +++ b/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',