From d517aa6c16e6361c3389ff9827a68164e21d5f00 Mon Sep 17 00:00:00 2001 From: Takeshi KOMIYA Date: Sat, 7 Mar 2020 13:19:37 +0900 Subject: [PATCH] Close #7079: Make autodoc_typehints=description formal --- CHANGES | 2 ++ doc/usage/extensions/autodoc.rst | 25 ++++--------------------- sphinx/ext/autodoc/__init__.py | 6 ++++-- sphinx/ext/autodoc/typehints.py | 18 +----------------- tests/test_ext_autodoc_configs.py | 13 +++++-------- 5 files changed, 16 insertions(+), 48 deletions(-) diff --git a/CHANGES b/CHANGES index 15c4f376c..fdac5368d 100644 --- a/CHANGES +++ b/CHANGES @@ -58,6 +58,8 @@ Features added * #6830: autodoc: consider a member private if docstring contains ``:meta private:`` in info-field-list * #7165: autodoc: Support Annotated type (PEP-593) +* #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 diff --git a/doc/usage/extensions/autodoc.rst b/doc/usage/extensions/autodoc.rst index ceef5f36a..9c3120eb5 100644 --- a/doc/usage/extensions/autodoc.rst +++ b/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. diff --git a/sphinx/ext/autodoc/__init__.py b/sphinx/ext/autodoc/__init__.py index 7abd6c879..e08a3d2ef 100644 --- a/sphinx/ext/autodoc/__init__.py +++ b/sphinx/ext/autodoc/__init__.py @@ -1003,7 +1003,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): @@ -1625,7 +1625,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') @@ -1634,5 +1635,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} diff --git a/sphinx/ext/autodoc/typehints.py b/sphinx/ext/autodoc/typehints.py index 64782dc1c..0d5cc5830 100644 --- a/sphinx/ext/autodoc/typehints.py +++ b/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) diff --git a/tests/test_ext_autodoc_configs.py b/tests/test_ext_autodoc_configs.py index b90772f6e..e250b21b3 100644 --- a/tests/test_ext_autodoc_configs.py +++ b/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()