Type hints (PEP 484) support for the Sphinx autodoc extension
Project description
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)Installation and setup
First, use pip to download and install the extension:
$ pip install sphinx-autodoc-typehints
Then, add the extension to your conf.py:
extensions = [
'sphinx.ext.autodoc',
'sphinx_autodoc_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.
Compatibility with sphinx.ext.napoleon
To use sphinx.ext.napoleon with sphinx-autodoc-typehints, make sure you load sphinx.ext.napoleon first, before sphinx-autodoc-typehints. See Issue 15 on the issue tracker for more information.
Project links
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for sphinx-autodoc-typehints-1.3.0.tar.gz
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 1a9df6cb3ba72453ea4bfbe96ea887abc0d796b2ce9508c2189217a1bb69b366 |
|
| MD5 | 8797006d36c7191077d9bd84b33b557a |
|
| BLAKE2b-256 | 96f2194721797bb0d96df240030dd513b41d47fe0640bbbd6a6978f0b488f847 |
Hashes for sphinx_autodoc_typehints-1.3.0-py3-none-any.whl
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 46cc9e985ee6d8bbbd07fffd95b815c39a72df6afb600f59671f85f7340e7d0d |
|
| MD5 | b4b0bf0e5cfe9c5bee4939a069479b65 |
|
| BLAKE2b-256 | e1c233f27e8c4dc7f84ec5873e39a0ded7e90b85b1d6dfbcce28b6b40863ddbd |
