Merge pull request #7268 from tk0miya/7079_autodoc_typehints_description

Close #7079: Make autodoc_typehints=description formal

CHANGES

@@ -59,6 +59,8 @@ Features added
   ``:meta private:`` in info-field-list
 * #7165: autodoc: Support Annotated type (PEP-593)
 * #2815: autodoc: Support singledispatch functions and methods
+* #7079: autodoc: :confval:`autodoc_typehints` accepts ``"description"``
+  configuration.  It shows typehints as object description
 * #6558: glossary: emit a warning for duplicated glossary entry
 * #3106: domain: Register hyperlink target for index page automatically
 * #6558: std domain: emit a warning for duplicated generic objects

doc/usage/extensions/autodoc.rst

@@ -466,9 +466,13 @@ There are also config values that you can set:
    following values:
 
    * ``'signature'`` -- Show typehints as its signature (default)
+   * ``'description'`` -- Show typehints as content of function or method
    * ``'none'`` -- Do not show typehints
 
    .. versionadded:: 2.1
+   .. versionadded:: 3.0
+
+      New option ``'description'`` is added.
 
 .. confval:: autodoc_warningiserror
 
@@ -596,24 +600,3 @@ member should be included in the documentation by using the following event:
       ``inherited_members``, ``undoc_members``, ``show_inheritance`` and
       ``noindex`` that are true if the flag option of same name was given to the
       auto directive
-
-Generating documents from type annotations
-------------------------------------------
-
-As an experimental feature, autodoc provides ``sphinx.ext.autodoc.typehints`` as
-an additional extension.  It extends autodoc itself to generate function document
-from its type annotations.
-
-To enable the feature, please add ``sphinx.ext.autodoc.typehints`` to list of
-extensions and set `'description'` to :confval:`autodoc_typehints`:
-
-.. code-block:: python
-
-   extensions = ['sphinx.ext.autodoc', 'sphinx.ext.autodoc.typehints']
-
-   autodoc_typehints = 'description'
-
-.. versionadded:: 2.4
-
-   Added as an experimental feature.  This will be integrated into autodoc core
-   in Sphinx-3.0.

sphinx/ext/autodoc/__init__.py

@@ -1004,7 +1004,7 @@ class FunctionDocumenter(DocstringSignatureMixin, ModuleLevelDocumenter):  # typ
                 (inspect.isroutine(member) and isinstance(parent, ModuleDocumenter)))
 
     def format_args(self, **kwargs: Any) -> str:
-        if self.env.config.autodoc_typehints == 'none':
+        if self.env.config.autodoc_typehints in ('none', 'description'):
             kwargs.setdefault('show_annotation', False)
 
         if inspect.isbuiltin(self.object) or inspect.ismethoddescriptor(self.object):
@@ -1744,7 +1744,8 @@ def setup(app: Sphinx) -> Dict[str, Any]:
     app.add_config_value('autodoc_default_options', {}, True)
     app.add_config_value('autodoc_docstring_signature', True, True)
     app.add_config_value('autodoc_mock_imports', [], True)
-    app.add_config_value('autodoc_typehints', "signature", True, ENUM("signature", "none"))
+    app.add_config_value('autodoc_typehints', "signature", True,
+                         ENUM("signature", "description", "none"))
     app.add_config_value('autodoc_warningiserror', True, True)
     app.add_config_value('autodoc_inherit_docstrings', True, True)
     app.add_event('autodoc-before-process-signature')
@@ -1753,5 +1754,6 @@ def setup(app: Sphinx) -> Dict[str, Any]:
     app.add_event('autodoc-skip-member')
 
     app.setup_extension('sphinx.ext.autodoc.type_comment')
+    app.setup_extension('sphinx.ext.autodoc.typehints')
 
     return {'version': sphinx.__display_version__, 'parallel_read_safe': True}

sphinx/ext/autodoc/typehints.py

@@ -18,21 +18,9 @@ from docutils.nodes import Element
 
 from sphinx import addnodes
 from sphinx.application import Sphinx
-from sphinx.config import Config, ENUM
 from sphinx.util import inspect, typing
 
 
-def config_inited(app: Sphinx, config: Config) -> None:
-    if config.autodoc_typehints == 'description':
-        # HACK: override this to make autodoc suppressing typehints in signatures
-        config.autodoc_typehints = 'none'  # type: ignore
-
-        # preserve user settings
-        app._autodoc_typehints_description = True  # type: ignore
-    else:
-        app._autodoc_typehints_description = False  # type: ignore
-
-
 def record_typehints(app: Sphinx, objtype: str, name: str, obj: Any,
                      options: Dict, args: str, retann: str) -> None:
     """Record type hints to env object."""
@@ -53,7 +41,7 @@ def record_typehints(app: Sphinx, objtype: str, name: str, obj: Any,
 def merge_typehints(app: Sphinx, domain: str, objtype: str, contentnode: Element) -> None:
     if domain != 'py':
         return
-    if app._autodoc_typehints_description is False:  # type: ignore
+    if app.config.autodoc_typehints != 'description':
         return
 
     signature = cast(addnodes.desc_signature, contentnode.parent[0])
@@ -141,10 +129,6 @@ def modify_field_list(node: nodes.field_list, annotations: Dict[str, str]) -> No
 
 
 def setup(app: Sphinx) -> Dict[str, Any]:
-    app.setup_extension('sphinx.ext.autodoc')
-    app.config.values['autodoc_typehints'] = ('signature', True,
-                                              ENUM("signature", "description", "none"))
-    app.connect('config-inited', config_inited)
     app.connect('autodoc-process-signature', record_typehints)
     app.connect('object-description-transform', merge_typehints)
 

tests/test_ext_autodoc_configs.py

@@ -462,10 +462,9 @@ def test_mocked_module_imports(app, warning):
     assert warning.getvalue() == ''
 
 
-@pytest.mark.sphinx('html', testroot='ext-autodoc')
+@pytest.mark.sphinx('html', testroot='ext-autodoc',
+                    confoverrides={'autodoc_typehints': "signature"})
 def test_autodoc_typehints_signature(app):
-    app.config.autodoc_typehints = "signature"
-
     options = {"members": None,
                "undoc-members": True}
     actual = do_autodoc(app, 'module', 'target.typehints', options)
@@ -513,10 +512,9 @@ def test_autodoc_typehints_signature(app):
     ]
 
 
-@pytest.mark.sphinx('html', testroot='ext-autodoc')
+@pytest.mark.sphinx('html', testroot='ext-autodoc',
+                    confoverrides={'autodoc_typehints': "none"})
 def test_autodoc_typehints_none(app):
-    app.config.autodoc_typehints = "none"
-
     options = {"members": None,
                "undoc-members": True}
     actual = do_autodoc(app, 'module', 'target.typehints', options)
@@ -564,8 +562,7 @@ def test_autodoc_typehints_none(app):
 
 
 @pytest.mark.sphinx('text', testroot='ext-autodoc',
-                    confoverrides={'extensions': ['sphinx.ext.autodoc.typehints'],
-                                   'autodoc_typehints': 'description'})
+                    confoverrides={'autodoc_typehints': "description"})
 def test_autodoc_typehints_description(app):
     app.build()
     context = (app.outdir / 'index.txt').read_text()