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.
My own brand new tool for rendering on the fly. The cool use is: put your
.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.
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.
Why ANOTHER render tool? Well, Pandoc has such amazing features that was put on my top list. Yes, it can render
.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.
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).
Write docs is not the most popular sport among developers, but these tools make that at least more fun. Enjoy!