基于Sphinx的文档的Markdown输出

Question

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

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

Answer 1

我没有找到任何可以获取reStructuredText文件并将它们转换为Markdown的内容,除了Pandoc,所以我为Docutils编写了一个自定义编写器(reStructuredText的参考实现以及Sphinx构建的基础).该代码可在GitHub上获得.

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

似乎要向Sphinx添加另一个编写器/输出格式,您需要使用扩展添加"构建器".

Answer 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

参考文献

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

ps。过时的原始答案（由于sphinx-markdown-builder现在可用）：在Sphinx项目站点上创建了直接Markdown输出支持的功能请求：https : //github.com/sphinx-doc/sphinx/issues/4219 感谢每个支持该github请求的人-区别！