如何配置sphinx autosummary在模块汇总表显示docstring标题后首行内容

autosummary默认会提取模块docstring的第一行非空内容作为汇总表的描述，因此你遇到的模块标题行被当作描述的问题是默认行为，可通过以下方案修改：

方案：自定义摘要提取逻辑（无侵入，无需改动现有docstring） #

直接在Sphinx项目的conf.py中添加如下代码即可：

import inspect
import sphinx.ext.autosummary.generate as ag

# 保存原有提取逻辑
original_get_summary = ag.get_summary

def custom_get_summary(obj, docstring, config):
    # 仅针对模块类型调整提取逻辑
    if inspect.ismodule(obj):
        # 清洗docstring空行
        valid_lines = [line.strip() for line in docstring.split('\n') if line.strip()]
        # 匹配「标题+下划线」的标准reST标题格式，跳过前两行取后续第一行内容
        if len(valid_lines) >=3 and all(c == '=' for c in valid_lines[1]):
            return [valid_lines[2]]
    # 类、函数等其他类型走原有默认逻辑
    return original_get_summary(obj, docstring, config)

# 替换原有提取函数
ag.get_summary = custom_get_summary

注意事项 #

• 确保conf.py中已经开启autosummary_generate = True配置
• 修改完成后执行make clean html重新生成文档即可生效
• 如果你使用的一级模块docstring标题标记不是=，可自行调整代码中的匹配字符为-/~等你实际使用的标题标记

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