Welcome to OGeek Q&A Community for programmer and developer-Open, Learning and Share
Welcome To Ask or Share your Answers For Others

Categories

0 votes
525 views
in Technique[技术] by (71.8m points)

python sphinx - Render output from markdown file inside .rst file

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?

See Question&Answers more detail:os

与恶龙缠斗过久,自身亦成为恶龙;凝视深渊过久,深渊将回以凝视…
Welcome To Ask or Share your Answers For Others

1 Reply

0 votes
by (71.8m points)

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:

与恶龙缠斗过久,自身亦成为恶龙;凝视深渊过久,深渊将回以凝视…
OGeek|极客中国-欢迎来到极客的世界,一个免费开放的程序员编程交流平台!开放,进步,分享!让技术改变生活,让极客改变未来! Welcome to OGeek Q&A Community for programmer and developer-Open, Learning and Share
Click Here to Ask a Question

...