Description

# sphinx-autodoc-typehints [](https://pypi.org/project/sphinx-autodoc-typehints/) [](https://pypi.org/project/sphinx-autodoc-typehints/) [](https://pepy.tech/project/sphinx-autodoc-typehints) [](https://github.com/tox-dev/sphinx-autodoc-typehints/actions/workflows/check.yaml) This [Sphinx](https://www.sphinx-doc.org/) extension reads your Python [type hints](https://docs.python.org/3/library/typing.html) and automatically adds type information to your generated documentation -- so you write types once in code and they appear in your docs without duplication. **Features:** - Adds parameter and return types from annotations into docstrings - Resolves types from [`TYPE_CHECKING`](https://docs.python.org/3/library/typing.html#typing.TYPE_CHECKING) blocks and [`.pyi` stub files](https://typing.python.org/en/latest/spec/distributing.html#stub-files) - Renders [`@overload`](https://docs.python.org/3/library/typing.html#typing.overload) signatures in docstrings - Extracts types from [attrs](https://www.attrs.org/) and [dataclass](https://docs.python.org/3/library/dataclasses.html) classes - Shows default parameter values alongside types - Controls union display style (`Union[X, Y]` vs `X | Y`) - Automatically fixes cross-references for stdlib types whose runtime module differs from their documented path - Supports custom type formatters and module name rewriting - Extracts descriptions from [`Annotated[T, Doc(...)]`](https://typing-extensions.readthedocs.io/en/latest/#Doc) metadata - Works with [Google and NumPy](https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html) docstring styles Sphinx has a built-in [`autodoc_typehints`](https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#confval-autodoc_typehints) setting (since v2.1) that can move type hints between signatures and descriptions. This extension replaces that with the features above. See [Avoid duplicate types with built-in Sphinx](#avoid-duplicate-types-with-built-in-sphinx). <!-- mdformat-toc start --slug=github --no-anchors --maxlevel=6 --minlevel=2 --> - [Installation](#installation) - [Quick start](#quick-start) - [How-to guides](#how-to-guides) - [Avoid duplicate types with built-in Sphinx](#avoid-duplicate-types-with-built-in-sphinx) - [Use with Google or NumPy docstring style](#use-with-google-or-numpy-docstring-style) - [Control return type display](#control-return-type-display) - [Change how union types look](#change-how-union-types-look) - [Show default parameter values](#show-default-parameter-values) - [Control overload signature display](#control-overload-signature-display) - [Keep type hints in function signatures](#keep-type-hints-in-function-signatures) - [Handle circular imports](#handle-circular-imports) - [Resolve types from `TYPE_CHECKING` blocks](#resolve-types-from-type_checking-blocks) - [Show types for `attrs` or `dataclass` fields](#show-types-for-attrs-or-dataclass-fields) - [Write a custom type formatter](#write-a-custom-type-formatter) - [Document a `NewType` or `type` alias without expanding it](#document-a-newtype-or-type-alias-without-expanding-it) - [Add types for C extensions or packages without annotations](#add-types-for-c-extensions-or-packages-without-annotations) - [Fix cross-reference links for stdlib types](#fix-cross-reference-links-for-stdlib-types) - [Fix cross-reference links for renamed modules](#fix-cross-reference-links-for-renamed-modules) - [Suppress warnings](#suppress-warnings) - [Reference](#reference) - [Configuration options](#configuration-options) - [Warning categories](#warning-categories) - [Explanation](#explanation) - [How it works](#how-it-works) - [How return type options interact](#how-return-type-options-interact) <!-- mdformat-toc end --> ## Installation ```bash pip install sphinx-autodoc-typehints ``` Then add the extension to your [`conf.py`](https://www.sphinx-doc.org/en/master/usage/configuration.html): ```python extensions = ["sphinx.ext.autodoc", "sphinx_autodoc_typehints"] ``` ## Quick start Instead of writing types in your docstrings, write them as Python type hints. The extension picks them up and adds them to your Sphinx output: ```python # Before: types repeated in docstrings def format_unit(value, unit): """ Format a value with its unit. :param float value: a numeric value :param str unit: the unit (kg, m, etc.) :rtype: str """ return f"{value} {unit}" # After: types only in annotations, docs generated automatically def format_unit(value: float, unit: str) -> str: """ Format a value with its unit. :param value: a