用Markdown代替RST使用sphinx
我恨RST，但爱狮身人面像。 有没有一种方法，狮身人面像阅读markdown而不是reStructuredText？
这样做的“正确”方法是编写一个用于降价的docutilsparsing器 。 （加上一个狮身人面像选项来selectparsing器。）它的优点是即时支持所有的docutils输出格式（但你可能不关心，因为大多数类似的减价工具已经存在）。 无需从头开发parsing器就可以实现的方法：
-
你可以作弊并编写一个“parsing器”，使用Pandoc将Markdown转换为RST，并将其传递给RSTparsing器:-)。
-
您可以使用现有的markdown-> XML分析器，并将结果（使用XSLT？）转换为docutils模式。
-
你可以采取一些现有的Python降价parsing器 ，让你定义一个自定义的渲染器，并使其构builddocutils节点树。
-
你可以分叉现有的RST阅读器，删除与降价无关的所有内容，并更改不同的语法（ 这种比较可能有帮助）…
编辑：我不build议这条路线，除非你准备严格testing它。 Markdown已经有太多细微差别的方言，这可能会导致另一个方面…
更新： https : //github.com/sgenoud/remarkdown是docutils的降价阅读器。 它没有采取任何上述捷径，但使用peg-markdown启发的欧芹 PEG语法。 还不支持指令。
更新： https : //github.com/rtfd/recommonmark是另一个docutils读者，本地支持ReadTheDocs。 派生自重新下载，但使用CommonMark-Py分析器。 不支持指令，但可以将或多或less自然的Markdown语法转换为合适的结构，例如指向toctree的链接列表。 对于其他需求，一个```eval_rst隔离块允许你embedded任何rST指令。
在任何情况下，您都需要发明Markdown的扩展来表示Sphinx指令和angular色 。 虽然你可能不需要所有的人，有些像.. toctree::是必不可less的。
我认为这是最难的部分。 在狮身人面像扩展已经比标记更丰富之前，它已经是reStructuredText了。 即使是大幅扩展的降价，如pandoc ，也大多是rSTfunction集的一个子集。 这是一个很好的理由！
在实施方面，最简单的是添加一个通用结构来expression任何docutilsangular色/指令。 语法灵感的明显候选者是：
- 属性语法，pandoc和一些其他的实现已经允许在许多内联和块结构。 例如
`foo`{.method}– >`foo`:method:。 - HTML / XML。 从
<span class="method">foo</span>转换为插入docutils内部XML的kludgiest方法！ - 某种YAML的指令？
但是这样一个通用的映射不会是最马马虎虎的解决scheme…目前讨论markdown扩展的最活跃的地方是https://groups.google.com/forum/#!topic/pandoc-discuss，https：:// github.com/scholmd/scholmd/
这也意味着你不能以某种方式重复使用markdownparsing器。 Pandoc再一次通过支持自定义过滤来达到作为文件转换的瑞士军刀的声誉 。 （事实上，如果我要这样做的话，我会尝试在docutils读者/变形记者/作者和pandoc读者/filter/作者之间build立一个通用桥梁，这比你需要的要多，但是回报会比sphinx /降价。）
另一个疯狂的想法：而不是扩展降价处理狮身人面像，扩展reStructuredText支持（大部分）降价超集！ 美丽的是，你将能够使用任何狮身人面像的function，但能够在减价中写入大部分内容。
已经有相当多的语法重叠 ; 最值得注意的是链接语法不兼容。 我认为如果你添加支持RST的降价链接和###风格的标题，并改变默认的`backticks`angular色为文字，也许改变缩进区块意味着文字（RST支持> ...对于今天的报价），你会得到支持大多数减价的可用的东西。
您可以在同一个Sphinx项目中使用Markdown和reStructuredText。 如何做到这一点简洁地logging在阅读文档 。 安装recommonmark（ pip install recommonmark ），然后编辑conf.py ：
from recommonmark.parser import CommonMarkParser source_parsers = { '.md': CommonMarkParser, } source_suffix = ['.rst', '.md']
我在Github（serra / sphinx-with-markdown）上创build了一个小示例项目，演示了它的工作原理。 它使用CommonMark 0.5.4和推荐0.4.0。
这不使用Sphinx，但MkDocs将使用Markdown构build您的文档。 我也很讨厌，到目前为止，真的很喜欢MkDocs。
Markdown和ReST做不同的事情。
RST提供了一个处理文档的对象模型。
Markdown提供了一种雕刻文本的方法。
从sphinx项目中引用Markdown的内容似乎是合理的，使用RST将整个信息体系结构和更大的文档stream转出去。 让降价做它做的，这是让作家专注于写文字。
有没有办法引用一个降价域，只是为了雕刻内容？ RST /狮身人面像似乎已经照顾了function，如toctree没有在降价复制。
它看起来像一个基本的实施已经进入狮身人面像的方式，但字还没有到位。 请参阅github问题评论
安装依赖关系：
pip install commonmark recommonmark
调整conf.py ：
source_parsers = { '.md': 'recommonmark.parser.CommonMarkParser', } source_suffix = ['.rst', '.md']
我与贝尼的build议是使用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(' '))
这现在正式支持： http : //www.sphinx-doc.org/en/stable/markdown.html
有一个解决方法。
sphinx-quickstart.py脚本生成一个Makefile。
每当你想生成文档以便将Markdown转换为reStructuredText时，你可以从Makefile中轻松地调用Pandoc。
