I hate RST but love sphinx. Is there a way that sphinx reads markdown instead of reStructuredText?
Join Stack Overflow to learn, share knowledge, and build your career.
|
Note that building documentation using maven and embedded Sphinx + MarkDown support is fully supported by following maven plugin : https://trustin.github.io/sphinx-maven-plugin/index.html
|
||||
|
|
|
This is now officially supported: http://www.sphinx-doc.org/en/stable/markdown.html |
|||
|
|
|
You can use Markdown and reStructuredText in the same Sphinx project. How to do this is succinctly documented on Read The Docs. Install recommonmark (
I've created a small example project on Github (serra/sphinx-with-markdown) demonstrating how (and that) it works. It uses CommonMark 0.5.4 and recommonmark 0.4.0. |
|||||||||||||||||||||
|
|
It looks like a basic implementation has made it's way into Sphinx but word has not gotten round yet. See github issue comment install dependencies:
adjust
|
|||||
|
|
The "proper" way to do that would be to write a docutils parser for markdown. (Plus a Sphinx option to choose the parser.) The beauty of this would be instant support for all docutils output formats (but you might not care about that, as similar markdown tools already exist for most). Ways to approach that without developing a parser from scratch:
UPDATE: https://github.com/sgenoud/remarkdown is a markdown reader for docutils. It didn't take any of the above shortcuts but uses a Parsley PEG grammar inspired by peg-markdown. Doesn't yet support directives. UPDATE: https://github.com/rtfd/recommonmark and is another docutils reader, natively supported on ReadTheDocs. Derived from remarkdown but uses the CommonMark-py parser. Doesn't support directives, but can convert more or less natural Markdown syntaxes to appropriate structures e.g. list of links to a toctree. For other needs, an In all cases, you'll need to invent extensions of Markdown to represent Sphinx directives and roles. While you may not need all of them, some like Implementation-wise, the easiest thing is adding a generic construct to express any docutils role/directive. The obvious candidates for syntax inspiration are:
But such a generic mapping will not be the most markdown-ish solution... Currently most active places to discuss markdown extensions are https://groups.google.com/forum/#!topic/pandoc-discuss, https://github.com/scholmd/scholmd/ This also means you can't just reuse a markdown parser without extending it somehow. Pandoc again lives up to its reputation as the swiss army knife of document conversion by supporting custom filtes. (In fact, if I were to approach this I'd try to build a generic bridge between docutils readers/transformers/writers and pandoc readers/filters/writers. It's more than you need but the payoff would be much wider than just sphinx/markdown.) Alternative crazy idea: instead of extending markdown to handle Sphinx, extend reStructuredText to support (mostly) a superset of markdown! The beauty is you'll be able to use any Sphinx features as-is, yet be able to write most content in markdown. There is already considerable syntax overlap; most notably link syntax is incompatible. I think if you add support to RST for markdown links, and |
|||||||||
|
|
I went with Beni's suggestion of using pandoc for this task. Once installed the following script will convert all markdown files in the source directory to rst files, so that you can just write all your documentation in markdown. Hope this is useful for others.
|
|||
|
|
|
This doesn't use Sphinx, but MkDocs will build your documentation using Markdown. I also hate rst, and have really enjoyed MkDocs so far. |
|||||||||||||||||||||
|
|
Markdown and ReST do different things. RST provides an object model for working with documents. Markdown provides a way to engrave bits of text. It seems reasonable to want to reference your bits of Markdown content from your sphinx project, using RST to stub out the overall information architecture and flow of a larger document. Let markdown do what it does, which is allow writers to focus on writing text. Is there a way to reference a markdown domain, just to engrave the content as-is? RST/sphinx seems to have taken care of features like |
|||||
|
|
There is a workaround. |
|||||||||||||||||
|
:param path:etc), see Napoleon extension. – Beni Cherniavsky-Paskin Apr 7 '14 at 22:21