extensions = [
"sphinx.ext.autodoc",
"sphinx.ext.napoleon",
"sphinx_autodoc_typehints",
"sphinx.ext.autosummary",
]
# sphinx.ext.napoleon
napoleon_use_rtype = typehints_use_rtype = False
# sphinx.ext.autodoc
# For this issue, this makes no difference regarding the signature, only regarding the description.
# Note that "description" and "both" add a separate "Return type" section which is also not
# formatted by typehints_formatter.
autodoc_typehints = "both"
# sphinx.ext.autosummary
autosummary_generate = True
# sphinx_autodoc_typehints
typehints_document_rtype = False
typehints_use_signature = True
typehints_use_signature_return = True
def typehints_formatter(annotation, config):
from typing import TypeVar
if isinstance(annotation, TypeVar) and annotation.__name__ == "Unformatted":
return "Formatted"
index.rst
.. autosummary::
my_module.my_function
my_module/__init__.py
from typing import TypeVar
Unformatted = TypeVar("Unformatted")
def my_function(arg: Unformatted) -> Unformatted:
"""
Do nothing
Args:
arg: An argument
Returns:
The argument returned
"""
return arg
Expected behavior
Types are formatted everywhere:
Parameter types in signature (because typehints_use_signature = True)
Return type in signature (because typehints_use_signature_return = True)
Types in "Parameters" section of description (because autodoc_typehints = "both")
Types in "Returns" section of description (because autodoc_typehints = "both")
Types in "Return type" section of description, if shown (if napoleon_use_rtype = typehints_use_rtype = True)
When type hints are shown in the signature, they are not passed through
typehints_formatter
.Example
conf.py
index.rst
my_module/__init__.py
Expected behavior
typehints_use_signature = True
)typehints_use_signature_return = True
)autodoc_typehints = "both"
)autodoc_typehints = "both"
)napoleon_use_rtype = typehints_use_rtype = True
)Actual behavior
Versions