Sphinx下RestructuredText列表渲染意外断裂问题求助

你遇到的随机渲染断裂问题，大概率是以下几个隐藏的语法/格式问题导致的：

• 缩进对齐不符合严格规范：reST要求列表续行的缩进必须严格和列表项首行第一个非标记字符对齐，比如#. Set xxx里Set的S是第4个字符（#. 占3个字符位），续行就必须缩进恰好3个空格，多1少1都会导致部分解析器识别为新段落，打断列表。
• 换行符类型不匹配：Windows下编辑生成的CRLF换行符，在Linux环境的Sphinx构建流程中可能被误识别为两次换行，相当于插入了空行，直接打断列表结构。
• 缩进混合Tab和空格：部分编辑器默认插入Tab，而不同解析器对Tab的宽度解析不同（有的按4空格算，有的按8空格算），就会出现本地测试正常、线上构建异常的随机问题。
• 行内角色跨拆分：你提供的异常代码中存在:guilabel角色未在当前行闭合就换行的错误写法，大部分reST解析器不支持跨行的行内角色，会导致语法解析逻辑错乱，进而打乱列表结构。

错误写法示例：

#. Set the :guilabel:`Output extent [optional] to
   :menuselection:`... --> Calculate from Layer --> Reprojected`

正确写法示例（闭合反引号后再拆分）：

#. Set the :guilabel:`Output extent [optional]` to
   :menuselection:`... --> Calculate from Layer --> Reprojected`

1. 开启编辑器的「显示空白字符」功能，逐行检查异常列表的续行缩进，确认和首行内容起始位置完全对齐，同时排查缩进中是否混入Tab、零宽空格等不可见字符。
2. 查看文件换行符类型，将所有文件的换行符统一设置为LF，避免跨平台解析异常。
3. 检查所有行内角色（:guilabel/:menuselection/:file等）的反引号是否在同一行闭合，禁止跨断行拆分角色内容。

• 统一全文档格式规范：约定固定的缩进空格数（推荐4空格），全程用空格缩进禁用Tab，所有文件统一使用LF换行。
• 优化跨行写法：长行拆分时优先在行内角色结束后、普通空格位置拆分，避免把单个角色、单个单词拆到两行。
• 本地最小化验证：如果问题依旧存在，把异常片段单独抽出来放到最小测试reST项目中构建，逐行修改排除冲突。

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