如何在Sphinx的rst文件中嵌入外部XML文件并保留语法高亮

直接使用裸.. include::指令引入XML文件无高亮的核心原因是：该指令默认仅做纯文本内容拼接，不会自动将引入内容标记为XML格式的代码块，自然无法触发语法高亮渲染。以下两种方案均为Sphinx原生支持，无需安装第三方扩展即可实现需求：

方案1：使用code-block指令的include参数（推荐） #

这是兼容性最好、配置最直观的写法，直接在代码块指令中指定要引入的外部文件路径，显式声明语言类型即可：

.. code-block:: xml
   :linenos:
   :caption: 业务规则配置示例
   :include: ./examples/config.xml

参数说明：

• xml：强制指定代码块语言为XML，调用Pygments的XML解析器做语法高亮，避免自动识别失效
• :linenos:：可选参数，添加后代码块会显示行号
• :caption:：可选参数，用于设置代码块的顶部标题
• :include:：参数值为目标XML文件相对于当前rst文档的相对路径，Sphinx构建时会自动读取文件内容嵌入代码块，渲染效果和手动粘贴XML内容完全一致

方案2：兼容include指令的写法 #

如果需要保留include的文件引入逻辑，可显式给include指令添加:code:参数标记内容类型，注意保持正确缩进：

.. code-block:: xml

   .. include:: ./examples/config.xml
      :code: xml

注意：include指令必须相对code-block指令缩进3个空格（符合rst代码块内容的缩进规则），否则引入内容会被识别为普通正文，无法触发代码高亮。

常见高亮失效排查点 #

• 未显式指定xml作为代码语言，Sphinx全局默认高亮语言不为XML时，会按纯文本或其他语言规则渲染
• 缩进不符合rst语法，引入内容未落在代码块作用域内
• 文件路径填写错误，构建时未成功读取XML内容，渲染为报错文本
• 构建前可执行sphinx-build -b html source build查看日志，若出现included file not readable类提示先修正文件路径

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