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