在Sphinx中使用MarkDown格式文档

因为在 本地化部署DeepSeek-R1 CPU架构 测试结果返回都是 MarkDown 格式，直接作为源码嵌入文档看起来很简陋不直观，所以考虑如何在Sphinx文档中嵌入部分 MarkDown 文档。

简单来说，使用 myst-parser 扩展，就可以非常轻松地引用 MarkDown 格式文档，会自动渲染HTML，就好像这些文档是标准的RST格式一样。

  • 安装 myst_parser :

安装 myst_parser 扩展
pip install myst-parser

  • 配置 conf.py :

配置 conf.py
extensions = [
        'sphinx.ext.graphviz',
        'sphinxnotes.strike',
        'sphinxcontrib.youtube',
        'sphinxcontrib.video',
        'myst_parser'
]

  • 在 .rst 文档中就可以引用 .md 文档:

引入 .md 文档
.. include:: README.md
   :parser: myst_parser.sphinx_

很神奇

需要注意， .md 文档需要严格遵循 MarkDown 格式，否则 build 时候会有报错

参考