IntenseWebs/sphinx
3
0
Fork 0
mirror of https://github.com/sphinx-doc/sphinx.git synced 2025-02-25 18:55:22 -06:00
Code Issues Packages Projects Releases Wiki Activity

autodoc: The default of autodoc_typehints_format becomes to 'smart'

Browse Source 
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
This commit is contained in:
Takeshi KOMIYA 2022-01-01 19:37:42 +09:00
parent 6f707a0944
commit 616f112e6a
11 changed files with 45 additions and 38 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
CHANGES
View File

@ -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
----------

7
doc/usage/extensions/autodoc.rst
View File

@ -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

2
sphinx/ext/autodoc/__init__.py
View File

@ -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)

12
tests/test_ext_autodoc.py
View File

@ -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() == ''

2
tests/test_ext_autodoc_autoattribute.py
View File

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

4
tests/test_ext_autodoc_autoclass.py
View File

@ -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 test_class_alias(app):
'.. py:attribute:: Alias',
' :module: target.classes',
'',
' alias of :py:class:`target.classes.Foo`',
' alias of :py:class:`~target.classes.Foo`',
]

2
tests/test_ext_autodoc_autodata.py
View File

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

2
tests/test_ext_autodoc_autofunction.py
View File

@ -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!",

2
tests/test_ext_autodoc_automodule.py
View File

@ -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

38
tests/test_ext_autodoc_configs.py
View File

@ -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`',
'',
]

8
tests/test_ext_autodoc_preserve_defaults.py
View File

@ -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',