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

Question

我想将我项目的 README.md 包含到我的 Sphinx 文档中，如 Can sphinx link to documents that are not located in directories below the root document? - 在生成的 Sphinx html 文档中，我在欢迎页面的 table 内容中单击 link，然后进入 README.md.

为此，创建了一个文档 readme_link.rst，其中包含行

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

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

然后我添加行

README <readme_link>

进入index.rst的目录树。随之而来的是，我的 README.md 没有被解析为 Markdown，而是被打印到页面上 as-is-text.

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

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

(当然不想重写为.rst.)

为什么 m2r 不起作用

我尝试关注，但这不起作用。我的 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 符号。那意味着我的 markdown 自述文件实际上并没有转换成 rst.

PS: 其他人试过类似的东西是 https://muffinresearch.co.uk/selectively-including-parts-readme-rst-in-your-docs/

Answer 1

您需要按如下方式编辑您的 readme_link.rst：

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

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

请注意，header 部分指定了 = 个字符，而不是 - 个字符。

造成这种情况的因素有两个。

包含的工作原理

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

因此，在解析 rst 文档时，您已经从 parent 和包含的文件中获得了一份完整的 rst 文档。一份完整的文件需要是有效 rst 文件，这将我们带到第二点...

Header 级别必须一致。

作为提醒，reStructuredText Spec 说明：

Rather than imposing a fixed number and order of section title adornment styles, the order enforced will be the order as encountered. The first style encountered will be an outermost title (like HTML H1), the second style will be a subtitle, the third will be a subsubtitle, and so on.

...

All section title styles need not be used, nor need any specific section title style be used. However, a document must be consistent in its use of section titles: once a hierarchy of title styles is established, sections must use that hierarchy.

因此，包含的child中的header级必须与parent中的header级一致。当 M2R 生成 rst 文档时，您（作为最终用户）不会具体说明使用哪个字符来定义每个部分级别。因此，要保持一致性，需要使用 scheme defined by M2R:

Rst heading marks are currently hard-coded and unchangeable.

H1: =, H2: -, H3: ^, H4: ~, H5: ", H6: #

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

另一种解决方案

reStructuredText 规范还指出：

Underline-only adornment styles are distinct from overline-and-underline styles that use the same character.

因此，您可以在 parent 文档中使用 overline-and-underline 样式，您在哪个级别使用哪些字符并不重要，因为 M2R 似乎只使用 underline-only 样式。所以这也行得通：

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

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

这有额外的好处（或负面的 - 取决于您的观点），即包含的 child 文档中的所有 header 现在都比他们在他们的文档中的级别低一级自己的。因此，child 在 parent 中更语义化 "nested"（单个 HTML 文档中的多个 h1 通常被认为不是语义的，尽管它技术上是 "valid")。当然，这可能是也可能不是您想要的，这就是为什么它被标记为 "alternate solution".

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。在您的文档中包含所需的降价文件

Link 你的文件 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，允许您将 README 的内容放入现有的 .rst 文件中，并且不会冲突与 .rst headers。明显的缺点是没有解析发生。

Answer 5

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

MyST-Parser allows 要嵌入 Markdown 文件中的 reStructuredText 样式指令。我们将使用该功能将您的 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 中，后者本身就在 Markdown 中，因此此时无需对 reStructuredText 进行任何转换。由于 myst_parser 扩展名，readme_link.md 将与所有其他源文件一起呈现为 HTML。

Answer 6

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

.. include:: README.md

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

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

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

Include my markdown README into Sphinx

python

markdown

restructuredtext

python-sphinx