15

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?

bad_coder
  • 11,289
  • 20
  • 44
  • 72
Jared Wilber
  • 6,038
  • 1
  • 32
  • 35
  • 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? – Steve Piercy Aug 30 '17 at 18:24
  • 1
    Also did you install and configure a Sphinx bridge, such as the Python package [recommonmark](http://www.sphinx-doc.org/en/stable/markdown.html)? There are also many flavors of markdown. – Steve Piercy Aug 30 '17 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. – Waylan Aug 30 '17 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. – Waylan Aug 30 '17 at 18:50
  • @StevePiercy It renders as unprocessed text. It does throw Warning messages about the text, e.g. `../tutorial.md:49: WARNING: Unexpected indentation.` I did install and configure my docs to use markdown with `recommonmark`; everything works perfect if I use solely a `.md` file. @Waylan Unfortunately, that's along the lines of what I figured. I suppose such behavior could make things quite convoluted anyways. Thanks for the helpful information! – Jared Wilber Aug 30 '17 at 20:41
  • 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. – Steve Piercy Aug 30 '17 at 21:47

1 Answers1

20

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:
Jared Smith
  • 19,721
  • 5
  • 45
  • 83
miyako
  • 316
  • 2
  • 3
  • 3
    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', #... ]` – Evgeny Nov 17 '18 at 20:16
  • 1
    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. – muammar Mar 14 '19 at 05:56
  • 3
    This [doesn't seem to work anymore](https://github.com/sphinx-doc/sphinx/issues/7420), since m2r is not actively maintained and [hasn't been updated to the newest sphinx api](https://github.com/sphinx-doc/sphinx/issues/7420#issuecomment-609814898) – JoVaRi Aug 11 '20 at 10:09
  • Seems to be working (again?) for me. – Bert Coerver Nov 29 '21 at 09:00