基于Sphinx的文档的Markdown输出

Question

我发现自己有一个用例，除了从基于Sphinx的文档源生成HTML和PDF之外，我还想生成Markdown reStructuredText版本的pandoc源文件。

我的初步研究未在 Sphinx 中找到任何核心或扩展支持。除了手动使用{{3}}或为任务创建新的 Sphinx 扩展外，是否有更简单/更集成的解决方案？

Answer 1

我没有找到任何可以接受reStructuredText文件并将其转换为Markdown的内容，除了Pandoc，所以我为Docutils编写了一个自定义编写器（reStructuredText的参考实现以及构建的Sphinx）。代码是available on GitHub。

请注意，它只是一个初始实现：它处理任何reStructuredText文档而没有错误（针对来自Docutils源存储库的 standard.txt 测试文档进行测试），但许多reStructuredText构造（例如替换） ，原始指令等）不受支持，因此不包括在Markdown输出中。我希望添加对链接，代码块，图像和表格的支持：对此的任何帮助都非常受欢迎 - 只需继续并分叉代码。

似乎要向Sphinx添加其他编写器/输出格式，您需要使用add a "builder" extension。

Answer 2

在Sphinx项目网站上创建了直接Markdown输出支持的功能请求：

https://github.com/sphinx-doc/sphinx/issues/4219

如果您有兴趣早点看到，请在Github上支持此请求。

更新Nov＆＃39; 18 ： sphinx-markdown-builder 现已推出 - 感谢@Jam Risser：

<强>安装

pip3 install sphinx-markdown-builder

<强>依赖关系

Python 3

<强>用法

在配置中加载扩展名。

conf.py

extensions = [
    'sphinx_markdown_builder'
]

如果使用 recommonmark ，请确保明确忽略构建文件，因为它们会与系统冲突。

conf.py

exclude_patterns = [
    'build/*'
]

使用Makefile构建markdown文件

make markdown

使用sphinx-build命令构建markdown文件

cd docs
sphinx-build -M markdown ./ build

<强>参考

• https://github.com/codejamninja/sphinx-markdown-builder/
• https://pypi.org/project/sphinx-markdown-builder/

Answer 3

如果您想使用pandoc，为什么不在第一次运行sphinx-quickstart.py将reStructuredText转换为Markdown时更改Makefile Sphinx生成的内容？
这是最简单的解决方案，尽管如果将其合并到Makefile中，Chris的解决方案也应该可以正常工作。