IntenseWebs/sphinx
3
0
Fork 0
mirror of https://github.com/sphinx-doc/sphinx.git synced 2025-02-25 18:55:22 -06:00
Code Issues Packages Projects Releases Wiki Activity

feat: add new option for autodoc_typehints_description_target to include undocumented return values

Browse Source
This commit is contained in:
gschwaer 2021-11-29 19:55:05 +01:00
parent e188d38e9d
commit 93e47600c0
2 changed files with 11 additions and 3 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
sphinx/ext/autodoc/__init__.py
View File

@ -2831,7 +2831,7 @@ def setup(app: Sphinx) -> Dict[str, Any]:
app.add_config_value('autodoc_typehints', "signature", True, app.add_config_value('autodoc_typehints', "signature", True,
ENUM("signature", "description", "none", "both")) ENUM("signature", "description", "none", "both"))
app.add_config_value('autodoc_typehints_description_target', 'all', True, 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_type_aliases', {}, True)
app.add_config_value('autodoc_warningiserror', True, True) app.add_config_value('autodoc_warningiserror', True, True)
app.add_config_value('autodoc_inherit_docstrings', True, True) app.add_config_value('autodoc_inherit_docstrings', True, True)

12
sphinx/ext/autodoc/typehints.py
View File

@ -63,8 +63,15 @@ def merge_typehints(app: Sphinx, domain: str, objtype: str, contentnode: Element
for field_list in field_lists: for field_list in field_lists:
if app.config.autodoc_typehints_description_target == "all": if app.config.autodoc_typehints_description_target == "all":
modify_field_list(field_list, annotations[fullname]) 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: 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: 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( def augment_descriptions_with_types(
node: nodes.field_list, node: nodes.field_list,
annotations: Dict[str, str], annotations: Dict[str, str],
force_rtype: bool
) -> None: ) -> None:
fields = cast(Iterable[nodes.field], node) fields = cast(Iterable[nodes.field], node)
has_description = set() # type: Set[str] 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. # Add 'rtype' if 'return' is present and 'rtype' isn't.
if 'return' in annotations: 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()
field += nodes.field_name('', 'rtype') field += nodes.field_name('', 'rtype')
field += nodes.field_body('', nodes.paragraph('', annotations['return'])) field += nodes.field_body('', nodes.paragraph('', annotations['return']))