feat: add new option for autodoc_typehints_description_target to incl…

…ude undocumented return values
sphinx-doc · Nov 2, 2021 · a2abd40 · a2abd40
1 parent 36eb4b7
commit a2abd40
Show file tree

Hide file tree

Showing 2 changed files with 11 additions and 3 deletions.
diff --git a/sphinx/ext/autodoc/__init__.py b/sphinx/ext/autodoc/__init__.py
@@ -2813,7 +2813,7 @@ def setup(app: Sphinx) -> Dict[str, Any]:
     app.add_config_value('autodoc_typehints', "signature", True,
                          ENUM("signature", "description", "none", "both"))
     app.add_config_value('autodoc_typehints_description_target', 'all', True,
-                         ENUM('all', 'documented'))
+                         ENUM('all', 'documented', 'returnvalue_and_documented_params'))
     app.add_config_value('autodoc_type_aliases', {}, True)
     app.add_config_value('autodoc_warningiserror', True, True)
     app.add_config_value('autodoc_inherit_docstrings', True, True)

diff --git a/sphinx/ext/autodoc/typehints.py b/sphinx/ext/autodoc/typehints.py
@@ -63,8 +63,15 @@ def merge_typehints(app: Sphinx, domain: str, objtype: str, contentnode: Element
         for field_list in field_lists:
             if app.config.autodoc_typehints_description_target == "all":
                 modify_field_list(field_list, annotations[fullname])
+            elif (app.config.autodoc_typehints_description_target
+                    == "returnvalue_and_documented_params"):
+                augment_descriptions_with_types(
+                    field_list, annotations[fullname], force_rtype=True
+                )
             else:
-                augment_descriptions_with_types(field_list, annotations[fullname])
+                augment_descriptions_with_types(
+                    field_list, annotations[fullname], force_rtype=False
+                )
 
 
 def insert_field_list(node: Element) -> nodes.field_list:
@@ -130,6 +137,7 @@ def modify_field_list(node: nodes.field_list, annotations: Dict[str, str]) -> No
 def augment_descriptions_with_types(
     node: nodes.field_list,
     annotations: Dict[str, str],
+    force_rtype: bool
 ) -> None:
     fields = cast(Iterable[nodes.field], node)
     has_description = set()  # type: Set[str]
@@ -166,7 +174,7 @@ def augment_descriptions_with_types(
 
     # Add 'rtype' if 'return' is present and 'rtype' isn't.
     if 'return' in annotations:
-        if 'return' in has_description and 'return' not in has_type:
+        if 'return' not in has_type and (force_rtype or 'return' in has_description):
             field = nodes.field()
             field += nodes.field_name('', 'rtype')
             field += nodes.field_body('', nodes.paragraph('', annotations['return']))