Repolode
Submit
tox-dev

tox-dev/sphinx-autodoc-typehints

A Sphinx extension that moves Python type hints into autodoc's parameter and return fields, with links and stub support.

View on GitHubWebsite
Stars
588
Forks
115
Open issues
0
Last commit
20 hours ago

What is it?

sphinx-autodoc-typehints is an extension for Sphinx's autodoc that reads the type hints of documented Python code and writes them into the parameter and return fields of the generated docs. Developers state each type once in the code instead of repeating it in docstrings.

The extension links each part of a type to its documentation and resolves names imported only under an `if TYPE_CHECKING:` block or declared in `.pyi` stub files. It also documents `@overload` variants and default values, and it can type Google and NumPy style docstrings written for napoleon or numpydoc.

The project's documentation compares it with Sphinx's built-in `autodoc_typehints` setting, showing differences such as typed `**kwargs` from `TypedDict`, `Annotated[..., Doc(...)]` descriptions, and `@deprecated` notices.

Key features

  • 01Writes type hints from code into autodoc parameter and return fields.
  • 02Links each part of a type to its documentation.
  • 03Resolves names imported under TYPE_CHECKING and declared in .pyi stubs.
  • 04Documents @overload variants and default values.
  • 05Types keyword arguments from TypedDict via **kwargs: Unpack[...].
  • 06Supports Google, NumPy, napoleon and numpydoc docstring styles.

Use cases

  • Documenting a typed Python library built with Sphinx autodoc.
  • Showing types from .pyi stubs for C extensions without annotations.
  • Keeping API docs in sync with type annotations instead of duplicating them in docstrings.

Quick start

  1. 1

    Install the extension from PyPI

    pip install sphinx-autodoc-typehints
  2. 2

    Add the extension to conf.py after sphinx.ext.autodoc

In collections

Static site generators & documentation tools

Topics

#sphinx#python#documentation#type-hints#autodoc#typehints

FAQ

What is sphinx-autodoc-typehints?
A Sphinx extension that moves Python type hints into autodoc's parameter and return fields, with links and stub support. sphinx-autodoc-typehints is an extension for Sphinx's autodoc that reads the type hints of documented Python code and writes them into the parameter and return fields of the generated docs. Developers state each type once in the code instead of repeating it in docstrings.
Is sphinx-autodoc-typehints free to use? What license does it have?
sphinx-autodoc-typehints is open source under the MIT license. Check the license terms before using it in commercial products.
Is sphinx-autodoc-typehints still maintained?
Actively maintained. The last commit to sphinx-autodoc-typehints was on Nov 6, 2026.
What can I use sphinx-autodoc-typehints for?
Documenting a typed Python library built with Sphinx autodoc. Showing types from .pyi stubs for C extensions without annotations. Keeping API docs in sync with type annotations instead of duplicating them in docstrings.
How do I install sphinx-autodoc-typehints?
Install the extension from PyPI: pip install sphinx-autodoc-typehints Add the extension to conf.py after sphinx.ext.autodoc
Where can I get sphinx-autodoc-typehints?
The source code and installation instructions are on GitHub: https://github.com/tox-dev/sphinx-autodoc-typehints

Summary generated by AI from the project's README. GitHub stats refresh daily.

Related projects