Read the Docs上Sphinx构建文档出现CSS异常（列表样式丢失）

问题根因 #

本地构建正常但Read the Docs（RTD）上列表被强制加上list-style: none样式，本质是RTD环境用的sphinx_rtd_theme版本和你本地的不一样——RTD会自动更新依赖，新版本主题的CSS规则改了，把列表项目符号给藏了。

解决办法 #

1. 锁定主题版本 #

在项目的docs目录下新建或编辑requirements.txt，把你本地用的sphinx_rtd_theme版本写死，比如：

sphinx_rtd_theme==1.2.2

然后去RTD的项目设置里，确保构建时会读取这个依赖文件。这样RTD就会用和你本地一模一样的主题版本，样式自然就对齐了。

2. 用自定义CSS强制覆盖 #

不想锁版本的话，直接加自定义CSS怼回去：

• 在docs/_static文件夹里新建custom.css，写这些内容：

.rst-content .section ul li,
.rst-content .section ol li {
    list-style: disc !important;
}
.rst-content .section ol li {
    list-style: decimal !important;
}

• 打开Sphinx的conf.py，加一段配置启用这个CSS：

def setup(app):
    app.add_css_file('custom.css')

不管主题怎么更新，自定义样式都会优先生效，保证列表项目符号正常显示。

3. 检查RTD构建配置 #

登进RTD项目后台的「高级设置」，确认这几点：

• 构建用的Python版本和你本地一致
• 有没有开「用setup.py把项目装到虚拟环境」，开了可能会搞乱依赖版本
• 手动触发一次重新构建，清掉旧缓存

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