Inspired by this issue comment and this example, I try to combine .rst restructured text files (for automatically generated documentation) with .md markdown files (for manual documentation), using the CommonMark parser. This works well (after #2841) when including markdown files in a toctree, but does not seem to work for .. include:: statements.
E.g. with the statement .. include:: ../README.md inside the (restructured text) INDEX.rst master file, the contents of README.md file are not parsed as markdown text but as restructured text!
What is the recommended way to include in the Sphinx documentation markdown files that typically reside in the root of a package (such as README.md, CHANGELOG.md or CONTRIBUTING.md), while parsing them correctly as markdown files?
Inspired by this issue comment and this example, I try to combine .rst restructured text files (for automatically generated documentation) with .md markdown files (for manual documentation), using the CommonMark parser. This works well (after #2841) when including markdown files in a toctree, but does not seem to work for
.. include::statements.E.g. with the statement
.. include:: ../README.mdinside the (restructured text)INDEX.rstmaster file, the contents of README.md file are not parsed as markdown text but as restructured text!What is the recommended way to include in the Sphinx documentation markdown files that typically reside in the root of a package (such as README.md, CHANGELOG.md or CONTRIBUTING.md), while parsing them correctly as markdown files?