使用狮身人面像与Markdown代替RST

Question

我讨厌RST，但爱狮身人面像。有没有一种方法让狮身人面像读取markdown而不是reStructuredText？

Answer 1

这样做的“正确”方法是编写docutils parser进行降价。 （加上一个狮身人面像选项来选择解析器。）它的优点将是对所有docutils输出格式的即时支持（但您可能并不在乎，因为大多数类似的降价工具已经存在）。方式来处理，没有从头开始开发一个解析器：

• 你可以欺骗和编写使用Pandoc到降价转换为RST并传递到RST分析器:-)一个“解析器”。

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

• 你可以拿一些existing python markdown parser，让你定义一个自定义的渲染器，并使其构建docutils节点树。

• 你可以用叉子叉现有RST读者，剥开一切无关的降价和改变不同的语法（this comparison可能帮助）...
  编辑：除非你准备在很大程度上，我不建议这条路线测试它。降价已经有太多微妙的不同方言，这将有可能导致尚未另外一...

UPDATE：https://github.com/sgenoud/remarkdown是docutils的减价读者。它没有采取任何上述快捷方式，但使用了Parsley PEG语法，其灵感来源于peg-markdown。 Doesn't yet支持指令。

更新：https://github.com/rtfd/recommonmark是另一个docutils读者，本地支持ReadTheDocs。派生自重新下载，但使用CommonMark-py解析器。不支持指令，但can convert或多或少自然的Markdown语法适用于合适的结构，例如指向toctree的链接列表。对于其他需求，```eval_rst fenced block可让您嵌入任何rST指令。

---

在所有案件，你需要创造降价的扩展来表示Sphinx directives and roles。虽然你可能不需要所有这些，但有些像.. toctree::是必不可少的。
这是我认为最难的部分。在狮身人面像扩展已经比标记更丰富之前，它是reStructuredText。即使大幅扩展降价，如pandoc's，也大多是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/

这也意味着你不能只重用降价解析器，但不以某种方式进行扩展。 Pandoc再次恪守其作为文件转换瑞士军刀的声誉，支持custom filtes。 （事实上​​，如果我想这样做，我会尝试在docutils读者/变形记者/作者和pandoc读者/过滤器/作者之间建立一个通用桥梁，这比你需要的要多，但是收益会比sphinx /降价）

---

替代疯狂的想法：而不是扩大降价处理狮身人面像，延长reStructuredText的支持（主要是）降价的超集！美丽的是，你将能够使用任何狮身人面像功能，但能够用降价编写大部分内容。

已经有considerable syntax overlap;最值得注意的是链接语法不兼容。我认为，如果您为RST减价链接和###风格的标题添加支持，并将默认的`backticks`角色更改为文字，并且可能会将缩进的块更改为意思字面（现在RST支持> ...），您将获得可用的支持大多数降价。

Answer 2

有一种解决方法。
sphinx-quickstart.py脚本生成一个Makefile。
您可以在每次想要生成文档以便将Markdown转换为reStructuredText时从Makefile轻松调用Pandoc。

Answer 3

Markdown和ReST做不同的事情。

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

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

想要从sphinx项目中引用Markdown内容中的一些内容似乎是合理的，它使用RST来截取整个信息体系结构和更大文档的流程。让降价做它做的事情，这可以让作家专注于撰写文字。

有没有办法引用一个降价域，只是为了雕刻内容？ RST /狮身人面像似乎已经照顾了诸如toctree之类的功能而没有在减价中重复它们。

Answer 4

这不使用狮身人面像，但MkDocs将使用Markdown构建您的文档。我也很讨厌，到目前为止，我真的很喜欢MkDocs。

Answer 5

我跟贝尼建议使用pandoc完成这个任务。安装后，以下脚本会将源目录中的所有降价文件转换为第一个文件，以便您可以用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 6

您可以在同一个Sphinx项目中使用Markdown和reStructuredText。如何在Read The Docs上简洁地记录这一点。安装recommonmark（pip install recommonmark），然后编辑conf.py：

from recommonmark.parser import CommonMarkParser 

source_parsers = { 
    '.md': CommonMarkParser, 
} 

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

---

我创建了一个小例子项目on Github (serra/sphinx-with-markdown)展示它是如何（以及）的作品。它使用CommonMark 0.5.4和推荐0.4.0。

Answer 7

它看起来像一个基本的实现已经进入狮身人面像的方式，但字还没有到位。 See github issue comment

安装依赖：

pip install commonmark recommonmark 

调整conf.py：

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

Answer 8

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

Answer 9

注意，使用行家和嵌入式狮身人面像+降价支持建立文档完全由后续支持荷兰国际集团的Maven插件：

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>