Support for ..include to parse Markdown files (README.md in parent dir)

[NumesSanguis]

Many Python repositories have a structure similar to:

project/
  docs/
    conf.py
    index.rst
  src/
  README.md

There is no clear instruction on how to including this README.md formatted as Markdown as part of Sphinx, while this is a common occurrence. Online certain solutions can be found:

1. Use .. include:: ../README.md in a readme_link.rst file.
   Problem: Parses the .md file as RST
2. Add paths to sys.path in conf.py like: sys.path.insert(0, os.path.abspath('..'))
   Problem: Somehow this doesn't work for me
3. Use a symlink to the README.md
   Problem: Is not cross-platform (does not work on Windows)
4. Copy the file on make time with a function.
   Problem: Far from ideal, needlessly making files.
5. Use M2R with .. mdinclude:: ../README.md; Only option working for me.
   Problem: Using extensions = ['m2r', 'recommonmark'] (or reversed list) gives the error: source_suffix '.md' is already registered in the m2r library.

• Would it be possible to support a similar .. mdinclude like M2R?
• Or have .. include:: first check the extension before parsing?
• Or what other clean solution does exist to include a README.md from a parent directory?

p.s. Relevant issue in Sphinx's repo: sphinx-doc/sphinx#701

[orsinium]

There is a trick on how to use m2r only for mdinclude and recommonmark for everything else:

life4/deal@7f33cbc

It's a code from m2r.py's setup() function.

[eric-wieser]

Problem: Parses the .md file as RST

A relevant sphinx issue for that: sphinx-doc/sphinx#2840

I have a proposed patch linked from that issue, that I used successfully in pygae/galgebra#413.

[chrisjsewell]

Just a little plug 😬 https://myst-parser.readthedocs.io/ would allow you do this, by having all your documentation as markdown, and supports including markdown files into other markdown, as the this test project demonstrates:
https://github.com/executablebooks/MyST-Parser/tree/master/tests/test_sphinx/sourcedirs/includes

[RabidCicada]

A warning for all the people trying to get a snippet similar to below to work based on @orsinium 's advice.

After research I found that all .md documents .. mdInclude::ed are being processed with m2r's parser but .md documents natively referenced in the toc are processessed by recommonmark.

I noticed this because I put debug statements in trying to understand why recommonmark wasn't converting relative links in README.md's that were .. mdIncludeed. m2r parsed fully all the .md's that are .. mdIncludeed while recommonmark processes all .md documents that are natively referenced in the toc.

    # from m2r to make `mdinclude` work
    app.add_config_value('no_underscore_emphasis', False, 'env')
    app.add_config_value('m2r_parse_relative_links', False, 'env')
    app.add_config_value('m2r_anonymous_references', False, 'env')
    app.add_config_value('m2r_disable_inline_math', False, 'env')
    app.add_directive('mdinclude', MdInclude)

[orsinium]

After research I found that all .md documents .. mdInclude::ed are being processed with m2r's parser but .md documents natively referenced in the toc are processessed by recommonmark.

Exactly, this is how this snippet is intended to work :)

There is a trick on how to use m2r only for mdinclude and recommonmark for everything else

[RabidCicada]

I assumed from your wording that you meant to use m2r for only the ..mdinclude linkage....but process all md's with recommonmark.
Seemed like what you were saying to me. Others might get bit by the same interpretation.

m2r for mdinclude only (linkage).
recommonmark for "everything else" meaning all other functions (parsing etc)

[chrisjsewell]

Note in https://myst-parser.readthedocs.io/en/latest/using/howto.html#include-a-file-from-outside-the-docs-folder-like-readme-md

```{include} ../../README.md
:relative-images:
```

Will now re-write local images to the correct path

[zillionare]

interestring that I found in recommonmark, it refers to ../README.md in it's index.md file. However, when I copied this, it doesn't work

[gmilde]

Docutils 0.17 added an experimental wrapper to integrate "recommonmark"
(Only tested with recommonmark version 0.4.0. the version that ships in Debian buster
Unfortunately, newer "recommonmark" versions introduced incompatible changes.)

To include a MarkDown (CommonMark) file, you just pass the new "parser" option to the "include" directive:

      .. include:: README.md
         :parser: markdown

If there is interest and feedback, we can try to bring this into shape for Docutils 0.18.

[chrisjsewell]

@gmilde recommonmark is already deprecated for myst-parser #221: myst-parser has already added support for the include (executablebooks/MyST-Parser#419) and there are plans to improve standalone docutils (as opposed to sphinx) support: executablebooks/MyST-Parser#426

[gmilde]

Switching to myst-parser may be too late for 0.18 but an option for 1.0.
The important point in Markdown support in Docutils is the chance to include a Markdown file from an rST file:

... include:: ../README.md
   :parser: markdown

This would help users/projects that want to maintain the bulk of the documentation in rST but include a README.md or similar files that are in Markdown format for external reasons.

[chrisjsewell]

Yep you can already do this with myst-parser:

   .. include::
      :parser: myst_parser.docutils_

   .. include::
      :parser: myst_parser.sphinx_