Sphinx文档配置：缩短继承路径与优化文档字符串解析

1. 缩短类/方法的继承路径与冗余标识 #

在docs/conf.py中添加以下配置，去除冗余的包/模块前缀，让文档结构更简洁：

# 隐藏模块名称前缀，仅显示类/函数名
add_module_names = False

# 简化类签名，将继承路径与类定义分离显示
autodoc_class_signature = "separated"

# 缩短类型提示中的完整路径，仅显示类/类型名
autodoc_typehints_format = "short"

• add_module_names = False：移除文档中类、函数名前的模块前缀（比如package_0.script_0.MyClass会变成MyClass）
• autodoc_class_signature = "separated"：将类的继承信息从类签名中分离，避免完整继承路径堆积在一行
• autodoc_typehints_format = "short"：把类型提示里的完整模块路径简化为类名

2. 避免函数文档字符串被压缩为单行 #

要保留文档字符串的原始换行和格式，在docs/conf.py中做如下修改：

方法1：保留原生reStructuredText格式 #

添加配置：

# 保留文档字符串的原始格式，不自动压缩换行
autodoc_keep_docstring_format = True

方法2：支持Google/Numpy风格文档字符串（推荐） #

如果你的代码使用Google或Numpy风格的文档字符串，先启用napoleon扩展，再配置格式保留：

# 在extensions列表中添加napoleon扩展
extensions.append('sphinx.ext.napoleon')

# 保留文档字符串的原始换行和结构
autodoc_keep_docstring_format = True

# 可选：根据你的文档风格调整以下参数
napoleon_google_docstring = True  # 启用Google风格解析
napoleon_numpy_docstring = False
napoleon_include_init_with_doc = True  # 包含__init__方法的文档

修改完成后，重新运行make html即可生效。

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