From a87153c018758a49b7dd601545c044576564652c Mon Sep 17 00:00:00 2001 From: Takeshi KOMIYA Date: Fri, 24 Dec 2021 10:14:19 +0900 Subject: [PATCH] autodoc: Rename autodoc_unqualified_typehints to autodoc_typehints_format (refs: #9931) --- CHANGES | 2 +- doc/usage/extensions/autodoc.rst | 11 ++++++++--- sphinx/ext/autodoc/__init__.py | 15 ++++++++------- tests/test_ext_autodoc_configs.py | 4 ++-- 4 files changed, 19 insertions(+), 13 deletions(-) diff --git a/CHANGES b/CHANGES index 77a901e85..653223e0b 100644 --- a/CHANGES +++ b/CHANGES @@ -13,7 +13,7 @@ Deprecated Features added -------------- -* #9075: autodoc: Add a config variable :confval:`autodoc_unqualified_typehints` +* #9075: autodoc: Add a config variable :confval:`autodoc_typehints_format` to suppress the leading module names of typehints of function signatures (ex. ``io.StringIO`` -> ``StringIO``) * #9831: Autosummary now documents only the members specified in a module's diff --git a/doc/usage/extensions/autodoc.rst b/doc/usage/extensions/autodoc.rst index d775ddee8..dfb08e688 100644 --- a/doc/usage/extensions/autodoc.rst +++ b/doc/usage/extensions/autodoc.rst @@ -662,10 +662,15 @@ There are also config values that you can set: .. __: https://mypy.readthedocs.io/en/latest/kinds_of_types.html#type-aliases .. versionadded:: 3.3 -.. confval:: autodoc_unqualified_typehints +.. confval:: autodoc_typehints_format - If True, the leading module names of typehints of function signatures are - removed (ex. ``io.StringIO`` -> ``StringIO``). Defaults to False. + This value controls the format of typehints. The setting takes the + 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``) .. versionadded:: 4.4 diff --git a/sphinx/ext/autodoc/__init__.py b/sphinx/ext/autodoc/__init__.py index 5ada06a6a..21e0a11cf 100644 --- a/sphinx/ext/autodoc/__init__.py +++ b/sphinx/ext/autodoc/__init__.py @@ -1295,7 +1295,7 @@ class FunctionDocumenter(DocstringSignatureMixin, ModuleLevelDocumenter): # typ def format_args(self, **kwargs: Any) -> str: if self.config.autodoc_typehints in ('none', 'description'): kwargs.setdefault('show_annotation', False) - if self.config.autodoc_unqualified_typehints: + if self.config.autodoc_typehints_format == "short": kwargs.setdefault('unqualified_typehints', True) try: @@ -1325,7 +1325,7 @@ class FunctionDocumenter(DocstringSignatureMixin, ModuleLevelDocumenter): # typ self.add_line(' :async:', sourcename) def format_signature(self, **kwargs: Any) -> str: - if self.config.autodoc_unqualified_typehints: + if self.config.autodoc_typehints_format == "short": kwargs.setdefault('unqualified_typehints', True) sigs = [] @@ -1566,7 +1566,7 @@ class ClassDocumenter(DocstringSignatureMixin, ModuleLevelDocumenter): # type: def format_args(self, **kwargs: Any) -> str: if self.config.autodoc_typehints in ('none', 'description'): kwargs.setdefault('show_annotation', False) - if self.config.autodoc_unqualified_typehints: + if self.config.autodoc_typehints_format == "short": kwargs.setdefault('unqualified_typehints', True) try: @@ -1589,7 +1589,7 @@ class ClassDocumenter(DocstringSignatureMixin, ModuleLevelDocumenter): # type: # do not show signatures return '' - if self.config.autodoc_unqualified_typehints: + if self.config.autodoc_typehints_format == "short": kwargs.setdefault('unqualified_typehints', True) sig = super().format_signature() @@ -2120,7 +2120,7 @@ class MethodDocumenter(DocstringSignatureMixin, ClassLevelDocumenter): # type: def format_args(self, **kwargs: Any) -> str: if self.config.autodoc_typehints in ('none', 'description'): kwargs.setdefault('show_annotation', False) - if self.config.autodoc_unqualified_typehints: + if self.config.autodoc_typehints_format == "short": kwargs.setdefault('unqualified_typehints', True) try: @@ -2172,7 +2172,7 @@ class MethodDocumenter(DocstringSignatureMixin, ClassLevelDocumenter): # type: pass def format_signature(self, **kwargs: Any) -> str: - if self.config.autodoc_unqualified_typehints: + if self.config.autodoc_typehints_format == "short": kwargs.setdefault('unqualified_typehints', True) sigs = [] @@ -2848,7 +2848,8 @@ 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_unqualified_typehints', False, 'env') + app.add_config_value('autodoc_typehints_format', "fully-qualified", 'env', + ENUM("fully-qualified", "short")) app.add_config_value('autodoc_warningiserror', True, True) app.add_config_value('autodoc_inherit_docstrings', True, True) app.add_event('autodoc-before-process-signature') diff --git a/tests/test_ext_autodoc_configs.py b/tests/test_ext_autodoc_configs.py index f3bcd6a97..3159e8a8f 100644 --- a/tests/test_ext_autodoc_configs.py +++ b/tests/test_ext_autodoc_configs.py @@ -1143,8 +1143,8 @@ def test_autodoc_typehints_description_and_type_aliases(app): @pytest.mark.sphinx('html', testroot='ext-autodoc', - confoverrides={'autodoc_unqualified_typehints': True}) -def test_autodoc_unqualified_typehints(app): + confoverrides={'autodoc_typehints_format': "short"}) +def test_autodoc_typehints_format_short(app): if sys.version_info < (3, 7): Any = 'Any' else: