Sphinx autodoc无法识别导入类型别名的文档字符串问题问询

问题核心 #

从私有模块导入函数、类时，Sphinx能正常抓取原模块的文档字符串，但类型别名（如示例中的Mydata）的自定义文档无法被识别，仅显示自动生成的描述。原因有两点：

• 普通赋值的类型别名，后续的字符串不会被关联为该别名的__doc__属性（仅模块、类、函数的文档字符串会自动绑定到__doc__）；
• 即使类型别名有了正确的__doc__，Sphinx默认会读取暴露模块中引用对象的信息，而非跟踪到原实现模块。

解决方案 #

步骤1：修复类型别名的文档字符串绑定

针对不同Python版本，选择正确的方式给类型别名添加文档字符串：

Python 3.10+（推荐）：使用typing.TypeAlias

TypeAlias是Python 3.10引入的类型别名标注，能让后续的文档字符串正确绑定到别名上：

# _aux.py
from typing import TypeAlias

def myfun(x):
    """Myfun is implemented in `_aux.py` and imported into `example.py`."""
    return 2*x

# 用TypeAlias标注后，文档字符串会绑定到Mydata
Mydata: TypeAlias = list[str]
"""
Mydata is implemented in `_aux.py` and imported into `example.py`.
"""

class Myclass():
    """
    Myclass is implemented in `_aux.py` and imported into `example.py`.
    """
    a_member: int
    another_member: float

Python 3.9及以下：手动赋值__doc__

如果无法使用TypeAlias，直接给类型别名的__doc__属性赋值：

# _aux.py
Mydata = list[str]
Mydata.__doc__ = """
Mydata is implemented in `_aux.py` and imported into `example.py`.
"""

步骤2：配置Sphinx抓取原模块文档

有两种方式让Sphinx读取原模块的类型别名文档：

方式一：修改autodata指令

在Sphinx文档中，直接指向原模块的类型别名，并用:module:选项修改显示的模块名（保持API对外展示的一致性）：

# My API

Sample API docs.

## Some stuff

Blah blah

```{eval-rst}
.. automodule:: example
   :members:
   :imported-members:
   :undoc-members:
# 指向原模块的Mydata，强制显示为example模块的成员
.. autodata:: _aux.Mydata
   :module: example

##### 方式二：全局自动跟踪（无需修改每个指令）
在Sphinx的`conf.py`中添加自定义处理函数，让autodoc自动跟踪导入对象到原模块：
```python
# conf.py
from sphinx.ext.autodoc import DataDocumenter

def setup(app):
    def import_data_docstring(app, what, name, obj, options, lines):
        # 仅处理数据类型（类型别名属于data）
        if what == 'data' and hasattr(obj, '__module__'):
            current_module = options.get('module')
            # 如果对象来自其他模块，尝试读取原模块的文档
            if obj.__module__ != current_module:
                import importlib
                mod = importlib.import_module(obj.__module__)
                # 获取原模块中的同名对象
                original_obj = getattr(mod, name.split('.')[-1], None)
                if original_obj and hasattr(original_obj, '__doc__') and original_obj.__doc__:
                    # 替换为原模块的文档字符串
                    lines[:] = original_obj.__doc__.splitlines()
    # 注册文档字符串处理钩子
    app.connect('autodoc-process-docstring', import_data_docstring)

之后直接使用.. autodata:: example.Mydata即可，Sphinx会自动抓取原模块的文档。

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