Sphinx ReadTheDocs主题下literalinclude文本块自动换行及自定义CSS失效排查

第一步：修复自定义CSS未加载的问题 #

• 确认目录结构匹配：html_static_path配置的路径是相对于conf.py所在目录的相对路径，先核对_static目录下确实存在custom.css文件，没有写错路径、文件名大小写问题；如果_static目录和conf.py不在同级路径，要调整为正确的相对路径（比如conf.py在docs/source/下，_static在docs/下，配置要写['../_static']）。
• 检查Sphinx版本兼容性：html_css_files配置项仅支持Sphinx 1.8.0及以上版本，版本过低时该配置不会生效，可通过sphinx --version检查版本，版本过低则升级Sphinx到当前稳定版。
• 清除构建缓存：增量构建会缓存旧的静态资源引用，新增自定义CSS后，先执行make clean清除旧构建产物，再重新执行make html生成新文档，不要直接增量构建。
• 核对部署配置：如果是托管到ReadTheDocs或GitHub Pages，要确认构建流程没有缓存旧的静态资源，没有禁用静态文件复制的配置。
• 验证加载状态：构建完成后打开生成的html页面源码，检查头部是否存在custom.css的引用标签，存在则说明加载成功。

第二步：替换为高优先级的换行CSS规则 #

就算自定义CSS加载成功，之前写的pre { white-space: pre-wrap; }会被ReadTheDocs主题的高优先级样式覆盖，直接替换custom.css里的内容为以下规则：

.rst-content div[class^='highlight'] pre {
    /* 自动换行，保留代码原有缩进 */
    white-space: pre-wrap;
    /* 允许长链接、长字符串强制断开换行 */
    word-break: break-word;
    /* 极端长内容保留滚动兜底，避免撑破页面布局 */
    overflow-x: auto;
}

该规则的选择器优先级和ReadTheDocs主题的代码块样式优先级一致，能直接覆盖默认的不换行配置，实现参考页面的换行效果。

第三步：核对literalinclude路径正确性 #

确认.. literalinclude::的路径是相对于当前RST文件的路径：

• 比如RST文件存放在docs/source/下，对应仓库根目录的LICENSE路径写../../LICENSE是正确的；如果RST文件直接放在docs/下，需要把路径改成../LICENSE。
• 构建后先确认LICENSE的内容能正常完整显示，排除路径错误导致的内容为空问题。

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