如何为Sphinx的.. include::指令指定代码类型实现JSON语法高亮

你可以直接使用Sphinx原生专门用于引入外部代码文件的literalinclude指令，完美匹配你不想两处维护代码的需求，完全支持code-block的所有配置项（名称、标题、行号、高亮等），写法如下：

.. literalinclude:: ../../examples/my_example.json
    :language: json
    :name: my_example.json
    :caption: my_example.json

如果你坚持要用include+:code:的写法，按照你的依赖版本选择对应写法即可：

• 若你的docutils版本低于0.17、Sphinx版本低于4.0，:code:参数不支持直接指定语言，需要额外加:language:选项声明代码类型：

  .. include:: ../../examples/my_example.json
      :code:
      :language: json
  

• 若你的依赖版本足够高，升级到最新版后即可直接使用:code: json的写法：

  pip install -U sphinx docutils
  

排错提示 #

修改后如果仍然不生效，先清空编译缓存重新构建即可，避免旧缓存影响渲染结果：

# 以HTML构建为例
make clean && make html

内容的提问来源于stack exchange，提问作者Steven C. Howell