将我的降价自述文件包含到 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 不工作

我试图跟踪 .rst 文件中 markdown 文件的渲染输出，但这不起作用。我的 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: 。我从 “标题级别不一致”是什么意思理解？ 我需要使用其他符号 - 但阅读它们后我意识到答案是指 rst 符号。那意味着我的降价自述文件实际上没有转换成 rst 。

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

原文由 Make42 发布，翻译遵循 CC BY-SA 4.0 许可协议

Answer 1

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

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

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

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

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

如何包含作品

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

因此，在解析 rst 文档时，您从父文件和包含文件中得到了一个完整的 rst 文档。一份完整的文件必须是 有效 的 rst 文件，这将我们带到了第二点……

标头级别必须一致。

提醒一下， reStructuredText 规范 解释说：

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

…

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

因此，包含的子项中的标题级别必须与父项中的标题级别一致。当 M2R 生成 rst 文档时，您（作为最终用户）不会具体说明使用哪个字符来定义每个部分级别。因此，为了保持一致性，需要使用 M2R 定义的方案：

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

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

替代解决方案

reStructuredText 规范还指出：

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

因此，您可以在父文档中使用上划线和下划线样式，并且您在哪个级别使用哪个字符并不重要，因为 M2R 似乎只使用下划线样式。所以这也行得通：

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

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

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

原文由 Waylan 发布，翻译遵循 CC BY-SA 4.0 许可协议

Answer 2

更新：听起来 https://stackoverflow.com/a/68005314/1187277 现在是推荐的解决方案。

---

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

1. 确保您具备必要的先决条件

（这些步骤也是接受答案所必需的。）

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

将文件链接到 toctree ：

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

   source/README.md

原文由 Shon 发布，翻译遵循 CC BY-SA 4.0 许可协议