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，而只是按原样打印到页面上。

我认为另一个想法可能是改为使用降价文件readme_link.md，但无法包含降价文件。

如何将我的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。确保您具备必要的先决条件

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

1.1确保您已安装降价渲染器：

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

1.2将recommonmark添加到extensions

中的conf.py列表中

1.3为降价文件制作符号链接

$ 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

Answer 3

如果您还遇到错误TypeError: add_source_parser()，请采用以下解决方法：

使用m2r2代替m2r。也就是说，

在文件readme_link.rst中，我们写

.. mdinclude:: ../README.md

并在文件conf.py中添加

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

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

Answer 4

一个相当简单的解决方案，如

.. literalinclude:: ../README.md

可能对你有用。

这不会解析 .md 文件，而是将其显示为文字代码块。

根据您的情况，这可能是一个可接受的解决方案。好消息是这不需要（可能不需要维护）扩展，适用于不支持符号链接的 Windows，允许您将自述文件的内容放入现有的 .rst 文件中，并且不会与 {{ 1}} 标题。明显的缺点是没有进行解析。

Answer 5

最简单的方法是使用MyST-Parser，它恰好是处理Markdown的扩展now recommended in Sphinx docs。不需要m2r。

MyST-Parser allows reStructuredText 样式指令嵌入到 Markdown 文件中。我们将使用该功能将您的 Markdown README.md 包含到一个占位符 Markdown 文件中，然后该文件将呈现为 HTML。

在conf.py中：

extensions = [
    # ...
    "myst_parser"
]

您的 readme_link 文件应该是 Markdown 格式而不是 reStructuredText，即创建一个包含 readme_link.md 指令的 include 文件：

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

该指令只是将 README.md 的内容转储到 readme_link.md 中，它本身在 Markdown 中，因此此时无需对 reStructuredText 进行任何转换。借助 readme_link.md 扩展名，myst_parser 将与所有其他源文件一起呈现为 HTML。

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