如何修改Sphinx的show-inheritance模板以显示基类完整限定名？

方法1：通过自定义扩展修正autodoc-process-bases钩子 #

你之前尝试的autodoc-process-bases钩子是可行的，大概率是处理逻辑没覆盖Sphinx内部的基类格式。以下是正确的实现：

1. 在项目根目录创建sphinx_extensions.py文件，写入以下代码：

def autodoc_process_bases(app, name, obj, options, bases):
    modified_bases = []
    for base in bases:
        # Sphinx内部会把基类存为(对象, 显示文本)的元组，需分别处理
        if isinstance(base, tuple):
            base_obj, _ = base
            full_qualname = f"{base_obj.__module__}.{base_obj.__name__}"
            modified_bases.append((base_obj, full_qualname))
        else:
            # 处理直接传入类对象的情况
            full_qualname = f"{base.__module__}.{base.__name__}"
            modified_bases.append((base, full_qualname))
    # 替换原基类列表
    bases[:] = modified_bases

def setup(app):
    app.connect('autodoc-process-bases', autodoc_process_bases)

2. 在你的Sphinx配置文件conf.py中添加这个扩展：

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

重新构建文档后，foobar.Box的继承信息就会显示为Bases: foo.Box, bar.Box，同时类标题仍保持objname的简洁格式。

方法2：覆盖Sphinx的autodoc模板 #

如果不想写扩展，也可以直接修改继承信息的显示模板：

1. 在你的文档目录下创建_templates/autodoc文件夹（如果不存在）。
2. 找到Sphinx安装目录下的class.rst模板（通常路径类似Lib/site-packages/sphinx/ext/autodoc/templates/autodoc/class.rst），复制到你刚创建的_templates/autodoc目录中。
3. 打开复制后的class.rst，找到继承相关的代码块：

{% if show_inheritance %}
   Bases: {{ ', '.join(bases) }}
{% endif %}

4. 修改为：

{% if show_inheritance %}
   Bases: {{ ', '.join([f"{base[0].__module__}.{base[0].__name__}" if isinstance(base, tuple) else f"{base.__module__}.{base.__name__}" for base in bases]) }}
{% endif %}

这种方式直接修改模板渲染逻辑，同样能实现带模块名的基类显示。

注意事项 #

• 方法1的扩展性更强，后续如果需要调整基类显示规则，只需修改扩展代码即可。
• 方法2需要注意Sphinx版本更新可能导致模板结构变化，若后续升级Sphinx后显示异常，需重新同步模板文件。

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