从 .rst 文件中的 markdown 文件渲染输出答案

【问题标题】：Render output from markdown file inside .rst file从 .rst 文件中的 markdown 文件渲染输出
【发布时间】：2018-02-08 13:26:44
【问题描述】：

我正在使用 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:

但是，生成的内容看起来很糟糕，因为它不会将降价呈现为降价。

我意识到我可以通过将整个文档编写为 .md 来避免这个问题，但是这个练习给我留下了以下问题：

是否可以将.md 内容呈现为降价，在.rst 文件中？

【问题讨论】：

虽然渲染的内容看起来很糟糕，而且它没有渲染为markdown，但它渲染成什么？更多信息会有所帮助。是否有任何错误或警告消息？
您是否也安装并配置了 Sphinx 桥接器，例如 Python 包 recommonmark？ markdown 也有很多种口味。
IIRC，不，这是不可能的。 Docutils（第一个解析器）不知道 Markdown。而include 是 docutils 特有的功能。因此，一旦 Sphinx 确定给定文件是 rst（而不是 Markdown），该文件就会作为 rst 传递给 Docutils，并且 Markdown 选项不再存在。至少这是我的理解。
当然，Sphinx 主要是一个包装器，它添加（和覆盖）许多 docutils 的指令。因此，期望 Sphinx 可以提供一个了解 Markdown 的 include 指令似乎是合理的。但是，IIRC include 指令包含 unprocessed 文本，该文本将在后面的步骤中解析。如果包含的文档使用不同的标记语言，这实际上不起作用。
警告表明 Sphinx 试图将 markdown 语法解释为 reStructuredText 语法，因为我无法回忆起 Markdown 中使用的任何缩进。因此，@Waylan 关于调用文件的上下文所写的内容对我来说听起来很合理。我也是这么想的。

【解决方案1】：

注意

mr2 扩展似乎已被放弃。您可以改用主动维护的 fork m2r2。

尝试M2R sphinx 扩展。

安装 m2r 并更改 conf.py 后，只需将 .. include 更改为 .. mdinclude 即可。

ml
==

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

w2v
^^^

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

【讨论】：

非常有用的答案，如果在其中显示install m2r and change conf.py，使用起来会更快。 install 是 pip install 和 conf.py 大约是extensions = ['m2r', #... ]
哇。这对我有用。我现在自行托管我的文档，这是唯一有效的方法。我无法在我的服务器上使用 recommonmark。
这个doesn't seem to work anymore，因为m2r没有被积极维护和hasn't been updated to the newest sphinx api
似乎对我有用（再次？）。