渲染 .rst 文件内 markdown 文件的输出

Question

我正在使用

Sphinx

来记录 Python 项目，并且希望将现有

.md

文件中的内容显示在

.rst

文件内。（我已经设置了

conf.py

以允许降价）。

例如，我有一个名为

tutorial.md

的文件。我还有一个

.rst

文件如下：

ml
==

w2v
^^^

.. automodule:: package.ml.w2v
:members:

我希望能够包含指向

tutorial.md

的链接，如下所示，这样

tutorial.md

的内容将在渲染时显示在文件中。这可以通过以下方式实现：

ml
==

Tutorial
--------
.. include:: ../tutorial.md

w2v
^^^

.. automodule:: package.ml.w2v
:members:

但是，生成的内容看起来很糟糕，因为它没有将 markdown 渲染为 markdown。

我意识到我可以通过将整个文档编写为

.md

来避免这个问题，但是这个练习给我留下了以下问题：

是否可以将

.md

内容呈现为降价，位于 .rst 文件的
inside
？

Answer 1

注意

mr2

扩展似乎已被放弃。您可以使用主动维护的 fork m2r2 来代替。

尝试 M2R sphinx 扩展。

安装 m2r 并更改 conf.py 后，只需将

.. include

更改为

.. mdinclude

即可正常工作。

ml
==

Tutorial
--------
.. mdinclude:: ../tutorial.md

w2v
^^^

.. automodule:: package.ml.w2v
:members:

Answer 2

自版本 0.19 (2022-06-21) 起，Docutils 的 “include”指令支持 :parser: 选项，允许将包含的文件的解析器设置为，例如 myst、pycmark 或 recommonmark。