Render output from markdown file inside .rst file

13
votes

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?

1
markdownpython-sphinxrestructuredtext
Although the rendered content looks bad, and it doesn't render as markdown, what does it render as? A little more information would be helpful. Are there any error or warning messages? - Steve Piercy
Also did you install and configure a Sphinx bridge, such as the Python package recommonmark? There are also many flavors of markdown. - Steve Piercy
IIRC, no it's not possible. Docutils (the rst parser) has no knowledge of Markdown. And include is a docutils specific feature. So once Sphinx determines that a given file is rst (rather than Markdown), that file is passed to Docutils as rst and the Markdown option no longer exists. At least that's my understanding. - Waylan
Of course, Sphinx is mostly a wrapper which adds (and overrides) many of docutils' directives. So it may seem reasonable to expect that Sphinx could provide an include directive which was knowledgeable of Markdown. However, IIRC the include directive includes the unprocessed text which is parsed in a later step. That doesn't really work if the included document uses a different markup language. - Waylan
The warning indicates that Sphinx was trying to interpret the markdown syntax as reStructuredText syntax, as I can't recall off the top of my head any indentation used in markdown. As such, what @Waylan wrote about the context of the calling file sounds reasonable to me. I figured as much, too. - Steve Piercy

1 Answers

18
votes

NOTE

The mr2 extension seems to be abandoned. You can use the actively-maintained fork m2r2 instead.

Original Answer:

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: