如何让Sphinx像记录函数声明一样记录自定义类型声明？

下面是几种实用的解决办法：

1. 用Sphinx自带的autodata指令+配置 #

• 第一步，在项目的conf.py里添加类型别名映射：

  autodoc_type_aliases = {'Type1': 'Type1'}
  

• 给你的类型声明加上文档字符串注释：

  from typing import Tuple
  Type1 = Tuple[str, float]
  """由字符串和浮点数组成的二元元组类型"""
  

• 在你的rst文档里，用autodata指令引用这个类型：

  .. autodata:: your_module_name.Type1
  

  这样生成的文档会自动把类型别名格式化成类似函数声明的样式，包含类型定义和注释。

2. 借助sphinx-autodoc-typehints扩展 #

• 先安装扩展：

  pip install sphinx-autodoc-typehints
  

• 在conf.py的extensions列表里加入这个扩展：

  extensions = [
      # 其他已有的扩展
      'sphinx_autodoc_typehints'
  ]
  

• 之后直接用autodata指令引用类型别名，扩展会自动解析并格式化类型信息，展示效果和函数声明一致，还能自动关联类型的详细定义。

3. 手动用RST指令定义 #

如果不想依赖扩展，也可以手动在RST文档里写：

.. py:data:: Type1
   :type: Tuple[str, float]

   由字符串和浮点数组成的二元元组类型

这种方式能完全自定义类型的展示样式，和函数声明的格式保持统一。

内容的提问来源于stack exchange，提问作者avsakharov