使用带有Markdown的sphinx而不是RST

Question

我讨厌RST,但喜欢狮身人面像.有没有办法让sphinx读取markdown而不是reStructuredText？

Answer 1

"正确"的方法是为markdown 编写docutils解析器.(另外还有Sphinx选项可以选择解析器.)这样做的好处是可以立即支持所有的docutils输出格式(但你可能不关心它,因为大多数类似的降价工具已经存在).如何在不从头开发解析器的情况下接近它:

• 您可以作弊并编写一个"解析器",它使用Pandoc将markdown转换为RST并将其传递给RST解析器:-).

• 您可以使用现有的markdown-> XML解析器并将结果(使用XSLT？)转换为docutils架构.

• 您可以使用一些现有的python markdown解析器,它允许您定义自定义渲染器并使其构建docutils节点树.

• 您可以分叉现有的RST阅读器,删除与markdown无关的所有内容并更改不同的语法(这种比较可能会有所帮助)...
  编辑:除非您准备对其进行大量测试,否则我不建议使用此路由.Markdown已经有太多微妙的不同方言,这可能会导致另一个......

更新: https ://github.com/sgenoud/remarkdown是docutils的降价阅读器.它没有采用任何上述快捷方式,而是使用受peg-markdown启发的Parsley PEG语法.尚不支持指令.

更新:https://github.com/rtfd/recommonmark,是ReadTheDocs原生支持的另一个docutils阅读器. 源自remarkdown但使用CommonMark-py解析器.不支持指令,但可以将或多或少自然的Markdown语法转换为适当的结构,例如指向toctree的链接列表.对于其他需求,可以使用```eval_rstfenced块嵌入任何rST指令.

在所有情况下,您都需要发明Markdown的扩展来表示Sphinx指令和角色.虽然你可能不需要所有这些,但有些.. toctree::是必不可少的.
我认为这是最难的部分.在Sphinx扩展之前,reStructuredText已经比降价更丰富了.即使是大量扩展的降价,例如pandoc,也主要是rST功能集的一个子集.这需要很多支持!

在实现方面,最简单的方法是添加一个通用构造来表达任何docutils角色/指令.语法灵感的明显候选者是:

• 属性语法,pandoc和其他一些实现已经允许在许多内联和块结构中.例如`foo`{.method}- > `foo`:method:.
• HTML/XML.从<span class="method">foo</span>仅仅插入docutils内部XML的kludgiest方法!
• 指令的某种YAML？

但是这样的通用映射不会是最降价十岁上下的解决方案.目前最活跃的地方,讨论降价扩展是https://groups.google.com/forum/#!topic/pandoc-discuss,https://开头github.com/scholmd/scholmd/

这也意味着你不能只重复使用markdown解析器而不以某种方式扩展它.通过支持定制过滤器, Pandoc再次辜负了瑞士军刀的文件转换声誉.(事实上​​,如果我接近这个,我会尝试在docutils读者/变换器/编写器和pandoc读取器/过滤器/编写器之间建立一个通用的桥梁.它比你需要的更多,但是收益会比sphinx /更宽降价.)

另类疯狂的想法:不是扩展markdown来处理Sphinx,而是扩展reStructuredText来支持(主要)markdown的超集!美丽的是你将能够按原样使用任何Sphinx功能,但能够在降价时写出大部分内容.

已经有相当多的语法重叠 ; 最值得注意的是链接语法是不兼容的.我认为如果你为RST添加对markdown链接和###-style标题的支持,并将默认`backticks`角色更改为literal,并且可能将缩进块更改为平均值(RST支持现在> ...报价),你将获得支持大多数markdown的可用内容.

Answer 2

您可以在同一个Sphinx项目中使用Markdown和reStructuredText.阅读文档简明扼要地记录了如何做到这一点.

安装Recommonmark(pip install recommonmark)然后编辑conf.py:

from recommonmark.parser import CommonMarkParser

source_parsers = {
    '.md': CommonMarkParser,
}

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

我在Github上创建了一个小例子项目(serra/sphinx-with-markdown),展示了它的工作原理.它使用CommonMark 0.5.4和Recommonmark 0.4.0.

Answer 3

这不使用Sphinx,但MkDocs将使用Markdown构建您的文档.我也讨厌第一个,到目前为止真的很喜欢MkDocs.

Answer 4

更新:现在官方支持并记录在sphinx文档中.

它看起来像一个基本的实现已经进入了Sphinx的方式但是还没有结束.请参阅github问题评论

安装依赖项:

pip install commonmark recommonmark

调整conf.py:

source_parsers = {
    '.md': 'recommonmark.parser.CommonMarkParser',
}
source_suffix = ['.rst', '.md']

Answer 5

Markdown和ReST做了不同的事情.

RST提供了处理文档的对象模型.

Markdown提供了一种雕刻文本的方法.

想要从您的sphinx项目中引用您的Markdown内容,使用RST来划分整个信息架构和更大文档的流程似乎是合理的.让markdown做它做的事情,这允许作家专注于写文本.

有没有办法引用降价域,只是按原样雕刻内容？RST/sphinx似乎已经处理了诸如toctree没有在markdown中复制它们之类的功能.

Answer 6

我和Beni建议使用pandoc完成这项任务.安装后,以下脚本会将源目录中的所有markdown文件转换为rst文件,以便您可以在markdown中编写所有文档.希望这对其他人有用.

#!/usr/bin/env python
import os
import subprocess

DOCUMENTATION_SOURCE_DIR = 'documentation/source/'
SOURCE_EXTENSION = '.md'
OUTPUT_EXTENSION = '.rst'

for _, __, filenames in os.walk(DOCUMENTATION_SOURCE_DIR):
    for filename in filenames:
        if filename.endswith('.md'):
            filename_stem = filename.split('.')[0]
            source_file = DOCUMENTATION_SOURCE_DIR + filename_stem + SOURCE_EXTENSION
            output_file = DOCUMENTATION_SOURCE_DIR + filename_stem + OUTPUT_EXTENSION
            command = 'pandoc -s {0} -o {1}'.format(source_file, output_file)
            print(command)
            subprocess.call(command.split(' '))

Answer 7

这是一个新选项。MyST 为 Markdown 添加了一些功能，允许 Sphinx 像 rst 一样构建文档。 https://myst-parser.readthedocs.io/en/latest/

Answer 8

现在官方支持:http://www.sphinx-doc.org/en/stable/markdown.html

Answer 9

我推荐使用MyST Markdown。这是一种 Markdown 风格，旨在引入 reStructuredText 的主要功能。MyST 代表 Markedly Structured Text，可以被认为是“rST but with Markdown”。

MyST 是 CommonMark 标准的超集，它被定义为通过markdown-it-py包对 CommonMark 的离散扩展的集合）。这意味着 CommonMark 语法与 MyST 一起开箱即用，但如果您愿意，您也可以使用更多语法功能。

MyST 对 reStructuredText 中的几乎所有功能都有语法，并针对完整的 Sphinx 测试套件进行了测试，以确保可以重新创建相同的功能。例如：

以下是在 MyST 中编写指令的方法：

```{directivename} directive options
:key: value
:key2: value2

Directive content
```

这是您在 MyST 中编写角色的方式

Here's some text and a {rolename}`role content`

MyST Markdown 的 Sphinx 解析器也有一些很好的 Sphinx 特定功能，比如使用 Markdown 链接语法 ( [some text](somelink)) 来处理 Sphinx 中的交叉引用。例如，您可以在 MyST 中定义一个标签，并引用它，如下所示：

(my-label)=
# My header

Some text and a [cross reference](my-label).

对于更完整的 MyST Markdown 语法列表，一个很好的参考是Jupyter Book 备忘单，其中列出了许多常见的文档需求和相应的 MyST 语法来完成它。（MyST 是作为 Jupyter Book 的一个组件创建的，尽管从技术角度来看它作为一个完全独立的项目存在）。

MyST 现在是Sphinx 文档和ReadTheDocs 文档中推荐的用于 Sphinx 的 Markdown 工具。

要将 MyST Parser 添加到您的 Sphinx 文档，只需执行以下操作：

pip install myst-parser

在 中conf.py，添加：

```{directivename} directive options
:key: value
:key2: value2

Directive content
```

您的 Sphinx 文档现在将能够解析 CommonMark Markdown 以及扩展的 MyST Markdown 语法！查看MyST 文档了解更多信息！

我希望这有助于澄清一些事情！