将我的降价自述文件包含到 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 的目录树。 随之而来的是，我的 README.md 不会被解析为 Markdown，而是按原样打印到页面上。

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

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

（当然我不想重写为.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 确保您已安装 Markdown 渲染器：

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

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

有关这方面的规范说明，请参阅 the documentation。

1.3 为您的降价文件创建符号链接

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

2。在您的文档中包含所需的降价文件

将文件链接到您的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

我已安装 myst-parser 扩展并尝试将 Markdown 文件包含到 .rst 文件中

.. include:: README.md

它没有被解析。添加了:parser: markdown 选项，但 docutils 抱怨未安装“recommonmark”扩展。我找到了一种方法来包含已解析的 md 文件：

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

Answer 5

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

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

在conf.py:

extensions = [
    # ...
    "myst_parser"
]

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

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

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

Answer 6

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

.. literalinclude:: ../README.md

可能会为您解决问题。

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

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