Merge pull request #10012 from tk0miya/9931_autodoc_typehints_format

autodoc: Rename autodoc_unqualified_typehints to autodoc_typehints_format (refs: #9931)

CHANGES

@@ -16,7 +16,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

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
+   This value controls the format of typehints.  The setting takes the
-   removed (ex.  ``io.StringIO`` -> ``StringIO``).  Defaults to False.
+   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
 

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

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})
+                    confoverrides={'autodoc_typehints_format': "short"})
-def test_autodoc_unqualified_typehints(app):
+def test_autodoc_typehints_format_short(app):
     if sys.version_info < (3, 7):
         Any = 'Any'
     else: