18

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?

Improve this question
6
  • 1
    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? Commented Aug 30, 2017 at 18:24
  • 1
    Also did you install and configure a Sphinx bridge, such as the Python package recommonmark? There are also many flavors of markdown. Commented Aug 30, 2017 at 18:31
  • 1
    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. Commented Aug 30, 2017 at 18:41
  • 1
    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. Commented Aug 30, 2017 at 18:50
  • 1
    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. Commented Aug 30, 2017 at 21:47

2 Answers 2

Reset to default
21

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:
Improve this answer
Sign up to request clarification or add additional context in comments.

4 Comments

Very useful answer, could be even quicker to use if install m2r and change conf.py were shown inside it. install is pip install and conf.py is about extensions = ['m2r', #... ]
Wow. This worked for me. I am now self-hosting my documentation and this is the only thing that worked. I could not make recommonmark to work on my server.
This doesn't seem to work anymore, since m2r is not actively maintained and hasn't been updated to the newest sphinx api
Seems to be working (again?) for me.
2

Since release 0.19 (2022-06-21), Docutils' "include" directive supports a :parser: option that allows setting the parser for the included file to, e.g., myst, pycmark, or recommonmark.

Try:

ml == Tutorial -------- .. include:: ../tutorial.md :parser: commonmark w2v ^^^ …
Improve this answer

Comments

Start asking to get answers

Find the answer to your question by asking.

Ask question

Explore related questions

See similar questions with these tags.