Enable Markdown files to be added to the Sphinx docs

[DominiqueMakowski]

We have .md files (the README.md that are in the benchmark folder) that it'd be nice to include in the docs.

See this issue: sphinx-doc/sphinx#2840

Waiting for this to be merged sphinx-doc/sphinx#7739

[rpanderson]

Current alternatives for achieving this are:

• MyST: A fully-functional markdown flavor and parser for Sphinx.
• Use m2r (not actively maintained) for the mdinclude directive and recommonmark for everything else, per this comment and example by @orsinium.

[DominiqueMakowski]

Thanks for the suggestions @rpanderson, I didn't know about MyST! Let me give it a try

[DominiqueMakowski]

I tried a few things but didn't manage to make it work 😞

The issue is that I'd like the documentation to mainly be built using .RST as it is for now, but only in some places include .md files. In particular, the .md files that I'd like to include are the README.md's that are present in the benchmark subfolders. (Note that these are not the package's README, but files that are called README so it gets displayed when visiting this page on github.)

For now, what I tried is, in the documentation, add an index.rst that points to another .rst that is supposed to include the .md file (similarly as it works for instance in this case). But I wasn't successful in making it work, and as you said the problem with m2r is that it's not maintained and therefore problematic to rely on.

Any suggestions are very much welcome ☺️

[rpanderson]

That appears possible using MyST, but I haven't got enough experience with it to readily diagnose your issue. I am familiar with applying my second recommendation to your use case, however (using m2r), which I've implemented a working example of in the mdinclude-example branch of my fork, which is built here. (See, for example, benchmark/ecg_preprocessing.)

To make this work, I also had to:

• Use HTML for any hyperlinks in bold/italics;
• Relative link figures from docs directory, i.e. prepend ../../benchmarks/ecg_preprocessing to image paths; and
• Remove line blank lines from references div.

I too would prefer to use MyST for this use case on my own projects and will let you know if/when I implement it.

[DominiqueMakowski]

which I've implemented a working example of in the mdinclude-example branch of my fork

@rpanderson splendid! Could you please consider making a PR with it! I'd be very happy to merge it :)

Relative link figures from docs directory

Does that mean that when viewing the README.md from github, the figures won't be visible anymore 'cause the relative link won't work? If so, I'd say it's acceptable for now as it's better to have them nicely displayed on the website than lost within github

[rpanderson]

Could you please consider making a PR with it!

Done. But you'll have to change the base branch to dev :-P

Does that mean that when viewing the README.md from github, the figures won't be visible anymore 'cause the relative link won't work?

Nope. This README.md and the docs source using mdinclude are incidentally at the same level of the repository, so the relative ../../ takes you to root in both cases, and the figures render on GitHub.