Type hints (PEP 484) support for the Sphinx autodoc extension
Project description
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.
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
The project was originally forked from here
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Hashes for sphinx-autodoc-napoleon-typehints-2.0.3.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 5a8527d8113e06b66ad86f8f93c179836a9c5232766b8e5bab061c1ab7e25e73 |
|
MD5 | e2f562956afe549243258f827d822466 |
|
BLAKE2b-256 | 0b2eba554b59085ee6f11c73f1e7e9c2b31a38aa335d44d39778644080443e1b |