将我的降价自述文件包含在Sphinx中

Question

我想将我的项目的README.md包含在我的Sphinx文档中，就像在Can sphinx link to documents that are not located in directories below the root document?中一样 - 这是在生成的Sphinx html文档中，我点击欢迎页面上的目录中的链接并转到README.md。

为此，创建了包含行的文档readme_link.rst

Readme File
-----------

.. include:: ../../README.md

我添加了这一行

README <readme_link>

进入index.rst的toctree。与此同时，我的README.md不会被解析为Markdown，而只是按原样打印到页面上。

我认为另一种想法可能是改为使用markdown文件readme_link.md，但是没有办法包含markdown文件。

如何将我的README.md解析为markdown？

（当然我不想把它重写为.rst。）

为什么m2r不起作用

我试图关注Render output from markdown file inside .rst file，但这不起作用。我的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:。我从What does "Title level inconsistent" mean?了解到我需要使用其他符号 - 但是阅读它们我意识到答案是指rst符号。这意味着我的降价自述文件实际上并未转化为rst。

PS：其他尝试类似事情的人是https://muffinresearch.co.uk/selectively-including-parts-readme-rst-in-your-docs/

Answer 1

你需要编辑你的readme_link.rst如下：

Readme File
===========

.. mdinclude:: ../../README.md

请注意，节标题用=字符而不是-字符指定。

有两个因素促成了这一点。

如何包括作品

标准include（不是mdinclude）实际上读取源文件的内容，只是复制原始文本代替指令。 M2R的mdinclude首先将源Markdown文本转换为rst，然后像include一样，复制该测试代替该指令。

因此，在解析rst文档时，您可以从父文件和包含文件中获得一个完整的rst文档。那个完整的文档需要是一个有效的rst文档，它将我们带到第二点......

标题级别必须一致。

提醒一下，reStructuredText Spec解释说：

而不是强加一个固定数量和部分标题装饰样式的顺序，强制执行的顺序将是遇到的顺序。遇到的第一个样式将是最外面的标题（如HTML H1），第二个样式将是副标题，第三个样式将是副字幕，依此类推。

...

不需要使用所有部分标题样式，也不需要使用任何特定的部分标题样式。但是，文档在使用节标题时必须保持一致：一旦建立了标题样式的层次结构，节必须使用该层次结构。

因此，包含的子级中的标头级别必须与父级中的标头级别一致。当M2R生成rst文档时，您（作为最终用户）无法确定哪个字符用于定义每个节级别的特异性。因此，为了保持一致性，您需要使用scheme defined by M2R：

• Rst标题标记目前是硬编码且不可更改的。 H1：=，H2：-，H3：^，H4：~，H5："，H6：#

如您所见，1级标题使用=字符，2级标题使用-字符。因此，需要在父readme_link.rst文件中使用相同的方案（您使用的是反向）。

另一种解决方案

reStructuredText规范还指出：

仅下划线装饰样式与使用相同字符的上划线和下划线样式不同。

因此，您可以在父文档中使用上划线和下划线样式，并且您使用哪个级别作为M2R只显示使用仅下划线样式无关紧要。所以这也会有效：

-----------
Readme File
-----------

.. mdinclude:: ../../README.md

这具有额外的好处（或者是否定的 - 取决于您的观点），所包含的子文档中的所有标题现在将比它们自己的低一个级别。因此，子代在语义上更“嵌套”在父代中（单个HTML文档中的多个h1通常被认为不是语义的，尽管它在技术上是“有效的”）。当然，这可能是您想要的，也可能不是，这就是为什么它被标记为“替代解决方案”。

Answer 2

如果您只想在项目中将markdown文档作为单独的文件包含（并且不需要将该文件的内容嵌入到.rst文件中），则有另一种方法：

1. Ensure you have the necessary prerequisites

（这些步骤也是接受答案的必要条件。）

1.1确保已安装markdown渲染器：

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

1.2将recommonmark添加到extensions的conf.py列表中

1.3为markdown文件创建符号链接

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

2.在您的文档中包含所需的markdown文件

链接toctree中的文件：

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

   source/README.md