基于 Sphinx 的文档的 Markdown 输出 [关闭]答案

【问题标题】：Markdown output for Sphinx based documentation [closed]基于 Sphinx 的文档的 Markdown 输出 [关闭]
【发布时间】：2012-11-15 11:43:41
【问题描述】：

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

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

【问题讨论】：

我没有看到任何现有的扩展。在你的第二段之前，我的第一个想法是建议 Pandoc :-) 所以我想这是你最好的选择。
@ReinoutvanRees：我现在正在使用 pandoc。也许我会调查 Sphinx 社区，看看是否有兴趣实现这样的东西并试一试。 :)
Using sphinx with Markdown instead of RST的可能重复

标签： markdown python-sphinx restructuredtext

【解决方案1】：

除了 Pandoc 之外，我没有找到任何可以获取 reStructuredText 文件并将它们转换为 Markdown 的东西，所以我为 Docutils 编写了一个自定义编写器（reStructuredText 的参考实现以及 Sphinx 的构建基础）。代码是available on GitHub。

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

似乎要向 Sphinx 添加另一种写入器/输出格式，您需要使用 extension 来 add a "builder"。

【讨论】：

感谢 Chris 让我们开始。我为此创建了一个构建器扩展。 github.com/codejamninja/sphinx-markdown-builder

【解决方案2】：

18 年 11 月更新：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

参考文献

ps。过时的原始答案（因为sphinx-markdown-builder 现在可用）：在 Sphinx 项目站点上为直接 Markdown 输出支持创建了功能请求： https://github.com/sphinx-doc/sphinx/issues/4219 感谢所有支持该 github 请求的人——这很重要！

【讨论】：

【解决方案3】：

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

【讨论】：