从.rst文件中的markdown文件渲染输出 [英] Render output from markdown file inside .rst file

问题描述

我正在使用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文件的内部 的减价标记?

解决方案

尝试 M2R sphinx扩展. /p>

https://github.com/miyakogi/m2r#sphinx-integration

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

ml
==

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

w2v
^^^

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

I am using Sphinx for documenting a Python project and would like to have content from an existing .md file display inside of a .rst file. ( I have already set up my conf.py to allow for markdown).

For example, I have a file called tutorial.md. I also have a .rst file as follows:

ml
==

w2v
^^^

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

I would like be able to include a link to tutorial.md as follows, such that the content of tutorial.md will display in the file upon rendering. This can be achieved with the following:

ml
==

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

w2v
^^^

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

However, the resulting content looks bad, as it doesn't render the markdown as markdown.

I realize I can avoid this issue by writing the entire documentation as .md, but this exercise has left me with the following question:

Is it possible to have .md content render as markdown, inside of an .rst file?

解决方案

Try M2R sphinx extension.

https://github.com/miyakogi/m2r#sphinx-integration

After install m2r and change conf.py, just change .. include to .. mdinclude would work well.

ml
==

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

w2v
^^^

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

这篇关于从.rst文件中的markdown文件渲染输出的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！