Get output from markdown file inside .rst file

Question

I am using Sphinx to document a Python project and would like to have content from an existing .md file inside a .rst file. (I already set my conf.py to allow markdowns).

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 to be able to include a link to tutorial.md as follows so that the contents of tutorial.md appear in the file when rendering. This can be achieved using the following:

 ml == Tutorial -------- .. include:: ../tutorial.md w2v ^^^ .. automodule:: package.ml.w2v :members: 

However, the result does not look good, since it does not display markdown as markdown.

I understand that I can avoid this problem by writing all the documentation as .md , but this exercise left me with the following question:

Is it possible to have .md rendering content as markdown inside a .rst file?

Answer 1

Try the M2R sphinx extension.

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

After installing m2r and changing conf.py, just change .. include to .. mdinclude to work well.

 ml == Tutorial -------- .. mdinclude:: ../tutorial.md w2v ^^^ .. automodule:: package.ml.w2v :members: