sphinx-autodoc-napoleon-typehints
This extension allows you to use Python 3 annotations for documenting acceptable argument types and return value types of functions. This allows you to use type hints in a very natural fashion, allowing you to migrate from this:
def format_unit(value, unit):
"""
Formats the given value as a human readable string using the given units.
:param float|int value: a numeric value
:param str unit: the unit for the value (kg, m, etc.)
:rtype: str
"""
return '{} {}'.format(value, unit)to this:
from typing import Union
def format_unit(value: Union[float, int], unit: str) -> str:
"""
Formats the given value as a human readable string using the given units.
:param value: a numeric value
:param unit: the unit for the value (kg, m, etc.)
"""
return '{} {}'.format(value, unit)There is also support for google docstrings or numpy docstrings with help of the napoleon napoleon sphinx extention. This means that even docstrings like this:
def format_unit_google(self, value: Union[float, int], unit: str, test: Optional[Union[Iterable, str]]) -> str:
"""
Formats the given value as a human readable string using the given units.
Args:
value: a numeric value
unit: the unit for the value (kg, m, etc.)
test: bla bla blathe unit for the value (kg, m, etc.)
Returns:
This function returns something of
value: and does not overwrite this part.
"""
return '{} {}'.format(value, unit)
def format_unit_numpy(self, value: Union[float, int], unit: str, test: Optional[Union[Iterable, str]]) -> str:
"""
Formats the given value as a human readable string using the given units.
Parameters
----------
value: a numeric value
unit: the unit for the value (kg, m, etc.)
test: bla bla blathe unit for the value (kg, m, etc.)
Returns
-------
This function returns something of
value: and does not overwrite this part.
"""
return '{} {}'.format(value, unit)the result for which is the same as above
Installation and setup
First, use pip to download and install the extension:
$Â pip install sphinx-autodoc-napoleon-typehints
Then, add the extension to your conf.py:
extensions = [
'sphinx.ext.autodoc',
'sphinx_autodoc_napoleon_typehints'
]How it works
The extension listens to the autodoc-process-signature and autodoc-process-docstring
Sphinx events. In the former, it strips the annotations from the function signature. In the latter,
it injects the appropriate :type argname: and :rtype: directives into the docstring.
Only arguments that have an existing :param: directive in the docstring get their respective
:type: directives added. The :rtype: directive is added if and only if no existing
:rtype: is found.
This extension does not currently have any configuration options.
Project links
- Source repository
- Issue tracker
- The project was originally forked from here
