Tools for Markdown and restructuredText

On my quest to find a way to render my Markdown and restructuredText docs on the fly, I’d found a lot of useful tools.

Markdown is my favorite lightweigth markup language. This blog is writen mostly in Markdown, thanks to Markdown on Save Worpress Plugin. I use it also for writtting simple tutorials, or step-by-step installation notes, or just to keep some tips for RegEx, for example.

And restructuredText can be used for the same uses, and thanks to some powerful options, is great to write long documentation, or even a book (Symfony2 docs and books are writen in restructuredText).

But… it’s so good to write docs using this markup languages, but NOT so good to read on that. It’s a must to convert or render them into another format, such HTML, ePub, PDF, etc.

So, what do I do? I use some tools, depending of my need.

DocRenderer

https://github.com/rafaelgou/doc-renderer

My own brand new tool for rendering on the fly. The cool use is: put your .md and .rst files on a web directory (with Apache + PHP), add 3 files on this directory and everything will be render with a nice Twitter Bootstrap visual. Great for my personal notes and local references.

Shinx-Pocoo

http://sphinx-doc.org/

That’s a FANTASTIC tool to render restructuredText docs. Not only renders .rst into HTML (and PDF, and ePub…), but also creates a fully browsable and searchable web page for any size of docs. You certainly have seen many FOSS documentation rendered in this way! I personaly have Symfony, Twig and other docs localy rendered just for quick reference. You can see a sample here.

Pandoc

http://johnmacfarlane.net/pandoc/

Why ANOTHER render tool? Well, Pandoc has such amazing features that was put on my top list. Yes, it can render .md and .rst, convert them to a lot of formats. BUT… most incredible for me, can render into web presentations formats like Reveal.js, DZSlides and others! This article put you in touch with this idea.

ReadTheDocs

https://readthedocs.org/

And… from my Bookmarks, ReadTheDocs. It’s a website where you can put your docs to be rendered with SphinxPocoo. Better than that, it can be syncronized with your Git repository. Even better than that, you have the site source code and you can make your own doc site (in your intranet, for example).

That’s all…

Write docs is not the most popular sport among developers, but these tools make that at least more fun. Enjoy!