Include my markdown README into Sphinx

UPDATE: It sounds like https://stackoverflow.com/a/68005314/1187277 is now the recommended solution.

There is an alternative approach, if you only want to include a markdown document in your project as a separate file (and don’t need to embed the contents of that file into an .rst file):

1. Ensure you have the necessary prerequisites

(These steps are also requisite for the accepted answer.)

1.1 Ensure you have the markdown renderer installed:

$ pip install -U sphinx>=1.8.3 recommonmark>=0.5.0

1.2 Add recommonmark to the list of extensions in conf.py

See the documentation for canonical instructions on this.

1.3 Make a symlink to your markdown file

$ cd docs             # or docs/source
$ ln -s ../README.md  # or to ../../README.md if using docs/source

2. Include the required markdown file in your docs

Link the file in your toctree:

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   source/README.md

If you also come across the error TypeError: add_source_parser(), here is the solution:

Using m2r2 instead of m2r. That is,

in the file readme_link.rst, we write

.. mdinclude:: ../README.md

and in the file conf.py we add

extensions = [
    # ...
    'm2r2'
]
# ...

# source_suffix = '.rst'
source_suffix = ['.rst', '.md']

A rather simplictic solution like

.. literalinclude:: ../README.md

might do the trick for you.

This will not parse the .md file but instead display it as a literal code block.

Depending on your situation that might be an acceptable solution. Good thing is that this does not require (potentially unmaintained) extensions, works on Windows which does not support symlinks, allows you to put the content of the README into an existing .rst file, and does not conflict with the .rst headers. The obvious downside is that no parsing is happening.

The simplest way is to use MyST-Parser, which happens to be the extension now recommended in Sphinx docs for handling Markdown. No need for m2r.

MyST-Parser allows reStructuredText-style directives to be embedded in Markdown files. We’ll use that feature to include your Markdown README.md into a placeholder Markdown file that will then get rendered to HTML.

In conf.py:

extensions = [
    # ...
    "myst_parser"
]

Your readme_link file should then be in Markdown format instead of reStructuredText i.e. create a readme_link.md file containing an include directive:

```{include} ../../README.md
```

This directive simply dumps the contents of README.md into readme_link.md which is itself in Markdown, so there’s no need to do any conversion to reStructuredText at this point. readme_link.md will get rendered into HTML along with all other source files thanks to the myst_parser extension.

I’ve installed myst-parser extension and tried to include a Markdown file into a .rst file

.. include:: README.md

It is not being parsed. Added :parser: markdown option, but docutils complains that "recommonmark" extension is not installed. I’ve found a way to include parsed md file:

.. include:: README.md
   :parser: myst_parser.sphinx_

1. Link your README.md form project root to the directory that your conf.py exists .
   ln -s {path to your README.md} {path to the dir that conf.py is in}

2. install the myst-parser package:
   pip install myst-parser

3. include the myst-parser in your conf.py file.

extensions = [
    "myst_parser",  # be carefull to use `_` and not `-`
]

4. create a .rst file (lets call it include_readme.rst for now) and paste the following block in it:

.. include:: CHANGELOG.md
   :parser: myst_parser.sphinx_

5. add the include_readme.rst to your index.rst file. your index.rst might look like this:

Welcome to documentation!
======================================

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   ...
   include_readme.  # this is a `.rst` file but u can exclude the `.rst` suffix here
   ...