RST中note指令生产环境构建出现嵌套缩进异常求助

问题描述 #

本地构建RST文档时，连续的.. note::和.. important::指令能正常独立堆叠；但部署到生产服务器后，连续的两个note指令会出现互相嵌套缩进的异常，important指令不受影响。

对应的RST代码：

.. note::

   Text 1

.. note::
   
   Text 2

.. important::

   Text 3

已尝试的无效操作：在指令两侧添加|换行符、将指令..调整为顶格无缩进。

排查方向与解决办法 #

1. 统一Sphinx版本 #

本地与生产环境的Sphinx版本差异是常见诱因，低版本Sphinx对连续同类型admonition指令存在解析bug。

• 执行sphinx-build --version分别查看本地和生产环境版本
• 将生产环境Sphinx升级到>=4.0的稳定版本，这类解析bug在高版本中已修复

2. 强制分隔同类型指令 #

如果无法升级Sphinx，可在连续的note指令之间添加空注释块强制分隔解析上下文：

.. note::

   Text 1

.. 

.. note::
   
   Text 2

.. important::

   Text 3

空的.. 注释会让解析器明确识别两个独立的admonition块，避免误判为嵌套结构。

3. 检查主题渲染逻辑 #

部分自定义或旧版Sphinx主题对admonition的渲染存在逻辑问题：

• 临时切换为默认主题（如alabaster）构建测试，若异常消失，说明是当前主题的bug，需更新主题或调整主题配置

4. 统一文件换行符 #

生产环境系统（如Linux）与本地（如Windows）的换行符（LF/CRLF）处理差异可能导致解析器误判缩进：

• 将RST文件转换为LF换行符后重新部署

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