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

Question

我想将我的项目包含README.md在我的Sphinx文档中,例如 Can sphinx链接到不在根文档下面的目录中的文档？ - 在生成的Sphinx html文档中,我点击欢迎页面上的目录中的链接,然后转到README.md.

为此,readme_link.rst创建了包含行的文档

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

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

我添加了这一行

README <readme_link>

进入toctree index.rst.与此同时,我README.md不会被解析为Markdown,而只是按原样打印到页面上.

我认为另一个想法可能是改为使用markdown文件readme_link.md,但是没有办法包含markdown文件.

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

(当然我不想把它重写为.rst.)

为什么m2r不起作用

我试图从.rst文件中的markdown文件中跟随Render输出,但这不起作用.我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/

Answer 1

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

.. include:: README.md

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

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

Answer 2

最简单的方法是使用 MyST-Parser，它恰好是Sphinx 文档中现在推荐的用于处理 Markdown 的扩展。不需要m2r。

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

在conf.py：

extensions = [
    # ...
    "myst_parser"
]

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

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

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

Answer 3

您需要编辑readme_link.rst如下:

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

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

请注意,节标题用=字符而不是-字符指定.

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

如何包括作品

标准include(非mdinclude)实际读取源文件的内容,只是复制原始文本代替指令.M2R mdinclude首先将源Markdown文本转换为rst,然后include复制该测试代替该指令.

因此,在rst解析文档时,您可以rst从父文件和包含文件中获得一个完整的文档.那个完整的文档需要是一个有效的 rst文档,这将我们带到第二点......

标题级别必须一致.

提醒一下,reStructuredText规范说明:

而不是强加一个固定数量和部分标题装饰样式的顺序,强制执行的顺序将是遇到的顺序.遇到的第一个样式将是最外面的标题(如HTML H1),第二个样式将是副标题,第三个样式将是副字幕,依此类推.

...

不需要使用所有部分标题样式,也不需要使用任何特定的部分标题样式.但是,文档在使用节标题时必须保持一致:一旦建立了标题样式的层次结构,节必须使用该层次结构.

因此,包含的子级中的标头级别必须与父级中的标头级别一致.当M2R生成rst文档时,您(作为最终用户)不会特定使用哪个字符来定义每个部分级别.因此,为了保持一致性,您需要使用M2R定义的方案.不幸的是,M2R没有记录它使用的方案(我提交了一份错误报告).但是,该方案在源代码中定义:

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

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

如您所见,1级标题使用该=字符,2级标题使用该-字符.因此,需要在父^文件中使用相同的方案(您使用的是反向).

另一种解决方案

reStructuredText规范还指出:

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

因此,您可以在父文档中使用上划线和下划线样式,并且您使用哪个级别作为M2R只显示使用仅下划线样式无关紧要.所以这也会有效:

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

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

这具有额外的好处(或者是否定的 - 取决于您的观点),所包含的子文档中的所有标题现在将比它们自己的低一个级别.因此,子代在语义上更"嵌套"在父代中(~单个HTML文档中的多个文档通常被认为不是语义的,尽管它在技术上是"有效的").当然,这可能是您想要的,也可能不是,这就是为什么它被标记为"替代解决方案".

Answer 4

如果您只想在项目中将markdown文档作为单独的文件包含(并且不需要将该文件的内容嵌入到.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.在您的文档中包含所需的markdown文件

链接您的文件toctree:

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

   source/README.md

Answer 5

如果您还遇到错误TypeError: add_source_parser()，这里是解决方案：

使用m2r2代替m2r. 那是，

在文件中readme_link.rst，我们写

.. mdinclude:: ../README.md

在conf.py我们添加的文件中

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

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