Support for files outside Sphinx project (README.md in parent dir)

[NumesSanguis]

Is your feature request related to a problem? Please describe.
Many Python repositories have a structure similar to:

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

This README is perfect for writing the project's introduction and some minimal usage examples. GitHub also renders these README's on the landing page (not when in the docs folder). This README is often in the format of Markdown, because in multi-contributer projects, this is the most familiar format.

Good documentation includes an introduction, which the README is perfect for, but currently you cannot include this README in the toctree, because it is outside the docs/ folder.

Describe the solution you'd like
One of the following:

1. Allow toctree parsing of source files outside the Sphinx project (which allows the extension recommonmark to parse the Markdown formatted README.md)
2. Allow passing on of a .md file to an extension before trying to parse the file as reST with the .. include:: ../README.md statement.

Describe alternatives you've considered

1. Use .. include:: ../README.md in a readme_link.rst file (also mentioned in issue: ..include:: statement doesn't parse markdown files correctly #2840).
   Problem: Parses the .md file as reST
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.

Additional context

• Similar issue can be found here: ..include:: statement doesn't parse markdown files correctly #2840 (but the difference is that this solution doesn't request Markdown parsing from Sphinx's side with .. include::, only to give extensions an interface to do so).
• Similar issue on the extension recommonmark to support Markdown files outside the toctree directory: Support for ..include to parse Markdown files (README.md in parent dir) readthedocs/recommonmark#191

[tk0miya]

+1: Reasonable. README is well known and well used file, and it is usually placed at root of the repository. It would be better to provide a way to include it to main documents (usually placed at directory like docs/).

Note: Sphinx expects all source files are placed under source directory. So it is hard to support external source files. So we have to think how to support it. I thought copying it temporarily is good workaround.

[NumesSanguis]

Copying will likely help many simple cases, but what if the README includes a reference to e.g. data/some_logo.png or other image file? All relative paths in the README will break if you only copy the README.

[mgeier]

@NumesSanguis There is one alternative that you didn't mention above:

6. Rename README.md to README.rst, then you can use it in an include directive.

You might see as a disadvantage that you have to use reST syntax in your README.rst, but objectively it's probably not.

[NumesSanguis]

Thank you for your suggestion @mgeier . That is indeed one way to tackle the issue, but I would argue against that it's objectively not a disadvantage. While obviously I'm familiar with the syntax, that's why I'm using sphinx, it's unfamiliar to many people not / little involved in Python documentation. Markdown is much more common in use, in coding projects of any language. While less advanced, it's faster to write and has a lower barrier of entrance. A quick edit is also done faster.

Therefore, it's quite common that a README.md is already in place before starting with any proper documentation using Sphinx. Having to do 1 adjustment to Sphinx to support Markdown is faster than rewriting the whole README into Sphinx. Markdown is already supported and the only problem here is that it's outside the directory.

So yes, if I absolutely need it, I can rewrite it to .rst, but I think it would help many people if a .md file outside the docs/ folder is supported. Rewriting it to an .rst would put-up an additional barrier for editors unfamiliar with the reST syntax.