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

Posted 2023-02-24

【中文标题】将我的降价自述文件包含到 Sphinx 中

【英文标题】：Include my markdown README into Sphinx

【发布时间】：2018-02-26 22:54:51

【问题描述】：

我想将我的项目的 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/

【问题讨论】：

@Waylan：这不起作用，请参阅更新的问题。

IIRC，在创建 Docutils 文档对象时检查一致的标题（在已经发生解析之后）。文档对象坚持具有一致的标题级别，错误消息只是假设源是rst。如果您使用的是 Docutils（Sphinx 是在其之上构建的），那么您绝对 必须 具有一致的标头级别。您使用什么标记语言并不重要。

作为测试，我建议将readme_link.rst 更改为markdown 文件（毕竟，M2R 将minclude 指令添加到Markdown 解析器中）然后看看会发生什么。我怀疑您可能会收到相同的错误消息。

最后，正如链接问题的 cmets 中所讨论的，除非您有一些非标准的修改，否则不可能将 include Markdown 文件转换为 rst 文件。 M2R 是我所知道的唯一这样的修改。因此，这仍然是重复的，这里没有与那里不同的答案。

@Waylan：我不太确定你建议我应该做什么。我包括m2r。我的标题与降价文档一致。据我了解，不可能将include 另一个文档放入降价文件中。

【参考方案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 通常被认为是不语义的，尽管它在技术上是“有效的”）。当然，这可能是也可能不是您想要的，这就是为什么它被标记为“替代解决方案”。

【讨论】：

mdinclude 不再受支持

@pjk 你有这个说法的来源吗？在 M2R 的docs 中仍然提到它。

基于 github.com/sphinx-doc/sphinx/issues/7420#issuecomment-609814898 和 github.com/sparkfun/Qwiic_Template_Py/issues/1 。 m2r2 似乎对我有用。无法让 m2r 完成我的工作。

啊，我明白了，它还没有更新到可以与 Sphinx 3 一起使用。看来m2r2 是一个更新的分支，可以与 Sphinx 3 一起使用。

m2r2 无法从 README 导入图像。任何提示为什么会这样？

【参考方案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

【讨论】：

我认为链接可能对版本控制有问题。有没有办法直接使用相对路径？我试过 ../README.md 。但 Sphinix 找不到。

对于步骤 1.2，您能否准确说明如何将 recommonmark 添加到 conf.py 中的扩展名列表中？

@chrisinmtown 我添加了指向文档相关部分的链接。我不想在这里的配置中“硬编码”，以免当他们改变某些东西时答案变得陈旧。

任何事情都可以随时改变 :) 这种提示真的很有帮助：extensions = [ 'recommonmark' ]

您认为现在只需点击一下官方文档，您所在位置的未来读者就会得到充分的指导吗？

【参考方案3】：

如果你也遇到错误TypeError: add_source_parser()，解决方法如下：

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

在文件readme_link.rst中，我们写

.. mdinclude:: ../README.md

我们在文件conf.py 中添加

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

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

【参考方案4】：

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

.. include:: README.md

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

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

【讨论】：

:parser: myst_parser.sphinx_ 对我来说是关键。在我添加之前解析无法正常工作。

我遇到了一个问题，它抱怨unknown option: "parser".。原来我在 0.17 之前有一个 docuitils 版本，升级它解决了这个问题。

这个解决方案现在在文档中:) myst-parser.readthedocs.io/en/latest/sphinx/…

【参考方案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。

【讨论】：

这是自2020年myst_parser正式推荐以来的正确答案

【参考方案6】：

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

.. literalinclude:: ../README.md

可能会为您解决问题。

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

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