Markdown output for Sphinx based documentation
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?
Answer
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.