使用Markdown的Sphinx而不是reST

我讨厌reST，但喜欢Sphinx。是否有一种方法，狮身人面像读取Markdown而不是reStructuredText?

63995 次浏览
小开

“proper"这样做的方法是为markdown写docutils解析器。(加上一个Sphinx选项来选择解析器。)这样做的好处是立即支持所有文档输出格式(但您可能并不关心这一点，因为大多数情况下已经存在类似的降价工具)。不需要从头开发解析器的方法:

  1. 你可以作弊，写一个“解析器”;它使用Pandoc将markdown转换为RST并将其传递给RST解析器:-)。

  2. 您可以使用现有的markdown- XML解析器并将结果(使用XSLT?)转换为docutils模式。

  3. 你可以使用一些现有的python markdown解析器，它允许你定义一个自定义渲染器，并让它构建文档节点树。

    4. 你可以fork现有的RST reader，删除所有与markdown无关的内容，并更改不同的语法(这种比较可能有帮助)…
    编辑:我不推荐这种方法，除非你准备进行大量测试。Markdown已经有太多微妙的不同方言，这可能会导致另一个…

更新: https://github.com/sgenoud/remarkdown是一个文档的降价阅读器。它没有采用上面的任何捷径，而是使用了欧芹 PEG语法，其灵感来自peg-markdown。

更新:https://github.com/readthedocs/recommonmark，是另一个docutils阅读器，原生支持ReadTheDocs。派生自remarkdown，但使用CommonMark-py解析器。

  • 它可以转换特定的或多或少的自然Markdown语法，以适当的结构，例如到toctree的链接列表。*没有角色的通用本地语法。
  • 支持用```eval_rst围栏块和DIRECTIVE_NAME:: ...指令的简写嵌入任何 rST内容，包括指令。

更新: 神秘岛是另一个documentins /Sphinx阅读器。基于markdown-it-py，兼容CommonMark。

  • 为角色提供通用的{ROLE_NAME}`...`语法。
  • 具有具有 ```{DIRECTIVE_NAME} ...隔离块的指令的通用语法。
在所有的情况下，你需要发明Markdown的扩展来表示Sphinx指令和角色。虽然你可能不需要全部，但像.. toctree::这样的一些是必不可少的。
我认为这是最难的部分。在Sphinx扩展之前的reStructuredText已经比markdown丰富了。即使是大量扩展的markdown，例如pandoc的，也主要是rST特性集的子集。那要去的地方可真多啊!< / p >

在实现方面，最简单的事情是添加一个泛型结构来表达任何docutils角色/指令。语法灵感的明显候选有:

  • 属性语法，pandoc和其他一些实现已经在许多内联和块结构上允许这种语法。例如`foo`{.method} ->`foo`:method:。
  • HTML / XML。从<span class="method">foo</span>到只插入文档内部XML的最笨拙的方法!
  • 某种用于指令的YAML ?
但是这样一个通用的映射将不是最低成本的解决方案… 目前讨论降价扩展最活跃的地方是https://groups.google.com/forum/ !主题/ pandoc-discuss， https://github.com/scholmd/scholmd/

这也意味着您不能只重用markdown解析器而不扩展它。通过支持自定义filtes, Pandoc再次不负其作为文档转换的瑞士军刀的声誉。(事实上，如果我要接近这个问题，我会尝试在docutils阅读器/transformer /writer和pandoc阅读器/filters/writer之间建立一个通用的桥梁。这比你需要的要多，但回报会比狮身人面像/降价要大得多。)

另一个疯狂的想法:与其扩展markdown来处理Sphinx，不如扩展reStructuredText来支持(大部分)markdown的超集!美妙之处在于，你可以使用任何Sphinx的特性，同时还可以以低价编写大部分内容。

已经有大量的语法重叠;最明显的是链接语法不兼容。我认为，如果你为RST添加对markdown链接的支持，以及__abc0风格的标题，并将默认的`backticks`角色更改为文字，并可能将缩进块更改为文字(RST现在支持> ...的报价)，你将得到支持大多数markdown的可用内容。

小开

有一个解决办法 sphinx-quickstart.py脚本生成一个Makefile 每次你想要生成文档以将Markdown转换为reStructuredText时，你都可以轻松地从Makefile中调用Pandoc

小开

Markdown和ReST做不同的事情。

RST为处理文档提供了一个对象模型。

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

从您的sphinx项目中引用Markdown内容，使用RST来stub出一个较大文档的整体信息架构和流程，这似乎是合理的。让markdown发挥它的作用，让作者专注于写作文本。

是否有一种方法来引用markdown域，只是按原样雕刻内容?RST/sphinx似乎已经处理了像toctree这样的特性，而没有在markdown中重复它们。

小开

这并不使用Sphinx，但是MkDocs将使用Markdown构建您的文档。我也讨厌rst，到目前为止我真的很喜欢MkDocs。

小开

我采纳了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(' '))
小开
你可以在同一个Sphinx项目中使用Markdown和reStructuredText。 如何做到这一点在斯芬克斯的文档中有简洁的文档。

安装myst-parser (pip install myst-parser)，然后编辑conf.py:

# simply add the extension to your list of extensions
extensions = ['myst_parser']


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

我已经创建了一个小的示例项目在Github (serra/sphinx-with-markdown)演示如何(和)它的工作。它使用Sphinx 3.5.4版本和myst-parser 0.14.0版本。

事实上，神秘岛解析器允许您在Markdown中编写整个Sphinx文档。它支持指令，并有几个扩展，你可以通过conf.py中的配置来启用。

MyST解析器要求Sphinx 2.1或更高版本。对于Sphinx的早期版本，您可以使用recommonmark在Sphinx中使用Markdown。签出这个答案的早些时候修正以找出如何。

小开

2021年5月更新:推荐为已弃用，支持神秘解析器(感谢astrojuanlu)

更新:现在正式支持并记录在斯芬克斯文档中。

看起来它的基本实现已经进入了Sphinx，但还没有消息传出去。见github问题评论

安装的依赖关系:

pip install commonmark recommonmark

调整conf.py:

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

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

也请参见https://myst-parser.readthedocs.io/en/latest/syntax/optional.html扩展，包括linkify使url自动链接。

小开

注意，以下maven插件完全支持使用maven和嵌入式Sphinx + MarkDown构建文档:

https://trustin.github.io/sphinx-maven-plugin/index.html

<plugin>
<groupId>kr.motd.maven</groupId>
<artifactId>sphinx-maven-plugin</artifactId>
<version>1.6.1</version>
<configuration>
<outputDirectory>${project.build.directory}/docs</outputDirectory>
</configuration>
<executions>
<execution>
<phase>package</phase>
<goals>
<goal>generate</goal>
</goals>
</execution>
</executions>
</plugin>
小开
这里有一个新选项。MyST为Markdown添加了一些功能，允许Sphinx像rst一样构建文档。 https://myst-parser.readthedocs.io/en/latest/ < / p >
小开

这是对recommonmark方法的更新。

pip install recommonmark

我个人使用Sphinx 3.5.1，所以

# for Sphinx-1.4 or newer
extensions = ['recommonmark']

检查官方文件在这里。

小开

我建议使用神秘岛减价。这是Markdown的一种风格，旨在引入reStructuredText的主要特性。MyST代表明显结构的文本，可以理解为“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现在是狮身人面像文件和ReadTheDocs文档中Sphinx的推荐Markdown工具。

要将MyST解析器添加到Sphinx文档中，只需执行以下操作:

pip install myst-parser

在conf.py中，添加:

extensions = [
...
"myst_parser",
...
]

您的Sphinx文档现在将能够解析CommonMark markdown以及扩展的MyST markdown语法!查看神秘岛的文档以获取更多信息!

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


提交答案