将我的降价自述文件包含在狮身人面像中
我想将我的项目的README.md到我的Sphinx文档中，如Can sphinx链接到不在根文档下的目录中的文档？ - 在Sphinx html文档中，我点击欢迎页面上目录中的链接，进入README.md 。
为此，将创建一个包含行的文档readme_link.rst
Readme File
-----------
.. include:: ../../README.md
并添加该行
README <readme_link>
进入index.rst的index.rst 。 README.md ，我的README.md不会被解析为Markdown，而只是按原样打印在页面上。
我认为另一种想法可能是使用降价文件readme_link.md ，但是无法使用降价包含文件。
如何将我的README.md解析为降价？
（当然，我不想把它改写为.rst）。
为什么m2r不工作
我试图按照渲染输出从markdown文件里面.rst文件，但这是行不通的。 我的README.md有一些标题
# First heading
some text
## Second heading 1
some text
## Second heading 2
some text
并且我得到错误WARNING: ../README.md:48: (SEVERE/4) Title level inconsistent: 。 我从“标题级别不一致”是什么意思？ 我需要使用其他符号 - 但读入它们，我意识到答案是指rst符号。 这意味着我的降价自述其实并没有被转化为rst 。
PS：其他人尝试类似的是https://muffinresearch.co.uk/selectively-including-parts-readme-rst-in-your-docs/
你需要编辑你的readme_link.rst ，如下所示：
Readme File
===========
.. mdinclude:: ../../README.md
请注意，部分标题用=字符而不是-字符指定。
有两个因素对此有所贡献。
如何包括作品
标准include （不是mdinclude ）实际上读取源文件的内容，并简单地复制原始文本来代替指令。 M2R的mdinclude首先将源Markdown文本转换为rst ，然后像include一样，拷贝测试代替指令。
因此，在分析rst文档时，您会从父文件和包含文件中获得一个完整的rst文档。 那一个完整的文件需要成为一个有效的rst文件，它将我们rst第二个要点......
标题级别必须一致。
提醒一下，reStructuredText规格说明如下：
强制执行的命令不会强加固定数量和顺序的部分标题装饰样式，而是遇到的顺序。 遇到的第一种风格是最外层的标题（如HTML H1），第二种风格是字幕，第三种风格是子标题，等等。
...
不需要使用所有章节标题样式，也不需要使用任何特定章节标题样式。 但是，文档在使用章节标题时必须保持一致：一旦标题样式的层次结构确立，章节必须使用该层次。
因此，包含的子级中的标题级别必须与父级中的标题级别一致。 由于M2R生成rst文档，因此您（作为最终用户）无法确定哪个字符用于定义每个部分级别。 因此，为了保持一致性，您需要使用M2R定义的方案。 不幸的是M2R没有记录它使用的方案（我提交了一个错误报告）。 但是，该方案在源代码中定义：
hmarks = {
1: '=',
2: '-',
3: '^',
4: '~',
5: '"',
6: '#',
}
正如你所看到的，1级标题使用=字符，而2级标题使用-字符。 因此，需要在父readme_link.rst文件中使用相同的方案（您正在使用相反的方法）。
另一种解决方案
reStructuredText规范还指出：
只有下划线装饰风格不同于使用相同字符的上下线样式。
因此，您可以在父文档中使用上下划线样式，并且使用哪个字符作为M2R的哪个级别似乎只使用下划线样式并不重要。 所以这也会有效：
-----------
Readme File
-----------
.. mdinclude:: ../../README.md
这有附加的好处（或消极的 - 取决于你的观点），所包含的子文档中的所有标题现在将低于他们自己的标题。 因此，孩子在语义上更“嵌套”在父母中（单个HTML文档中的多个h1通常被认为不是语义的，尽管它在技术上是“有效的”）。 当然，这可能是也可能不是你想要的，这就是为什么它被标记为“替代解决方案”。
如果您只想在项目中包含降价文档（并且不需要将该文件的内容嵌入到.rst文件中），则还有一种替代方法：
1.确保你有必要的先决条件
（这些步骤对于接受的答案也是必需的。）
1.1确保您已安装降价渲染器：
$ pip recommonmark
1.2确保狮身人面像被配置为呈现降价
将这些行添加到项目的conf.py ：
# Render these files as indicated
source_parsers = {
'.md': 'recommonmark.parser.CommonMarkParser'
}
2.在文档中包含所需的降价文件
链接您的toctree的文件：
.. toctree::
:maxdepth: 2
:caption: Contents:
source/README
在这种情况下，我将我的源代码目录source/README.md中的文件README.md source/README.md到项目根目录中的README.md 。