基于Sphinx的文档的Markdown输出 [英] Markdown output for Sphinx based documentation
问题描述
我发现自己有一个用例，除了从我的 Sphinx 生成HTML和PDF之外文档来源，我还要生成一个 Markdown 版本的 reStructuredText 源文件。
我的初步研究没有'在狮身人心中找到任何核心或扩展支持。除了手动使用 pandoc 或为该任务创建新的Sphinx扩展程序之外，是否有一个更简单/更集成的解决方案？
我没有找到可以采用reStructuredText文件和转换除了Pandoc之外，他们还要Markdown，所以我为 Docutils （参考实现reStructuredText以及什么Sphinx构建）编写了一个自定义的作者。代码是在GitHub上可用。请注意，它只是一个初始化的实现：它处理任何reStructuredText文档而不会出现错误（针对来自Docutils的 standard.txt 测试文档进行测试源存储库），但是不支持许多reStructuredText结构（例如替换，原始指令等），因此不包括在Markdown输出中。我希望添加对链接，代码块，图像和表格的支持：对此的任何帮助都是值得欢迎的 - 只需继续执行代码。
似乎要向Sphinx添加另一个作者/输出格式，您需要使用添加构建器 http://sphinx-doc.org/extensions.html#extensions\">延伸。
I found myself with a use case, where in addition to generating HTML and PDF from my Sphinx based documentation sources, I would also like to generate a Markdown version of the reStructuredText source files.
My preliminary research didn't find any core or extension support for this in Sphinx. Other than manually using pandoc or creating a new Sphinx extension for the task, is there be a simpler/more integrated solution for this?
I didn't find anything which could take reStructuredText files and convert them to Markdown except for Pandoc, so I wrote a custom writer for Docutils (the reference implementation of reStructuredText and what Sphinx is built upon). The code is available on GitHub.
Note that it is only an initial implementation: it handles any reStructuredText document without error (tested against the standard.txt test document from the Docutils source repository) but many of the reStructuredText constructs (e.g. substitutions, raw directives etc.) are not supported and so not included in the Markdown output. I hope to add support for links, code blocks, images and tables: any help towards this is more than welcome - just go ahead and fork the code.
It seems that to add another writer/output format to Sphinx you need to add a "builder" using an extension.
这篇关于基于Sphinx的文档的Markdown输出的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！
