使用Furo Sphinx主题生成API文档时参数名与类型异常大写如何解决

问题原因 #

这个问题确实是Furo主题默认样式导致的，你的配置本身没有操作错误。Furo默认对参数列表的定义项（即参数名、参数类型）添加了text-transform: uppercase的全大写转换规则，才会出现你看到的渲染异常。

修复方案 #

只需要添加自定义CSS覆盖默认样式即可，操作步骤非常简单：

• 在你的Sphinx项目根目录下找到_static文件夹，如果不存在就手动新建一个
• 在_static文件夹中新建名为custom.css的样式文件，写入以下内容：

/* 覆盖Furo默认的参数名大写规则 */
dl.field-list > dt {
    text-transform: none;
}

• 打开你的conf.py配置文件，添加以下配置项加载自定义CSS：

html_css_files = [
    'custom.css',
]

• 重新执行sphinx-build构建命令，就能看到参数名、类型恢复为正常的大小写格式。

可选优化配置（numpydoc兼容） #

如果你后续还遇到其他numpydoc渲染异常，可以在conf.py中添加以下常用的numpydoc兼容配置：

# 关闭numpydoc自动生成的类成员冗余目录
numpydoc_show_class_members = False
numpydoc_class_members_toctree = False

内容的提问来源于stack exchange，提问作者Kaan Güven