Repolode
提交项目
tox-dev

tox-dev/sphinx-autodoc-typehints

一个 Sphinx 扩展，把 Python 类型提示自动写入 autodoc 生成的参数与返回值字段中。

在 GitHub 查看官网
Star
588
Fork
115
未关闭 Issue
0
最近提交
19小时前

这是什么？

sphinx-autodoc-typehints 是 Sphinx autodoc 的扩展，它读取被文档化的 Python 代码中的类型提示，并将其写入生成文档的参数和返回值字段。开发者只需在代码中声明一次类型，无需在 docstring 中重复书写。

该扩展会把类型的每个部分链接到对应文档，并能解析仅在 `if TYPE_CHECKING:` 块中导入或在 `.pyi` 存根文件中声明的名称。它还支持 `@overload` 多重签名和默认值显示，并能为采用 napoleon 或 numpydoc 的 Google 风格、NumPy 风格 docstring 补充类型。

项目文档将其与 Sphinx 内置的 `autodoc_typehints` 设置做了对比，展示了基于 `TypedDict` 的 `**kwargs` 类型标注、`Annotated[..., Doc(...)]` 描述以及 `@deprecated` 提示等差异。

核心功能

  • 01将代码中的类型提示写入 autodoc 的参数和返回值字段。
  • 02把类型的每个部分链接到对应文档。
  • 03解析 TYPE_CHECKING 块中导入及 .pyi 存根中声明的名称。
  • 04支持 @overload 多重签名和默认值显示。
  • 05通过 **kwargs: Unpack[...] 为 TypedDict 关键字参数添加类型。
  • 06兼容 Google、NumPy、napoleon 和 numpydoc 风格的 docstring。

适用场景

  • 为使用 Sphinx autodoc 的带类型标注 Python 库生成文档。
  • 为没有类型标注的 C 扩展展示 .pyi 存根中的类型。
  • 让 API 文档与类型标注保持同步，避免在 docstring 中重复书写。

快速上手

  1. 1

    从 PyPI 安装该扩展

    pip install sphinx-autodoc-typehints
  2. 2

    在 conf.py 中将扩展添加到 sphinx.ext.autodoc 之后

收录于专题

静态网站生成器与文档工具

标签

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

常见问题

sphinx-autodoc-typehints 是什么？
一个 Sphinx 扩展，把 Python 类型提示自动写入 autodoc 生成的参数与返回值字段中。 sphinx-autodoc-typehints 是 Sphinx autodoc 的扩展，它读取被文档化的 Python 代码中的类型提示，并将其写入生成文档的参数和返回值字段。开发者只需在代码中声明一次类型，无需在 docstring 中重复书写。
sphinx-autodoc-typehints 可以免费使用吗？用的什么许可证？
sphinx-autodoc-typehints 以 MIT 许可证开源。用于商业产品前，请先确认许可证条款。
sphinx-autodoc-typehints 还在维护吗？
活跃维护中。sphinx-autodoc-typehints 最近一次提交是在 2026年11月6日。
sphinx-autodoc-typehints 适合用来做什么？
为使用 Sphinx autodoc 的带类型标注 Python 库生成文档。 为没有类型标注的 C 扩展展示 .pyi 存根中的类型。 让 API 文档与类型标注保持同步，避免在 docstring 中重复书写。
sphinx-autodoc-typehints 怎么安装和运行？
从 PyPI 安装该扩展: pip install sphinx-autodoc-typehints 在 conf.py 中将扩展添加到 sphinx.ext.autodoc 之后
在哪里获取 sphinx-autodoc-typehints？
源代码和安装说明在 GitHub 上：https://github.com/tox-dev/sphinx-autodoc-typehints

概要由 AI 根据项目 README 生成；GitHub 数据每日更新。

相关项目