Na minha cruzada para encontrar um jeito de renderizar automaticamente minhas documentações escritas em Markdown e restructuredText, encontrei algumas ferramentas muito úteis.
Markdown é a minha linguagem de marcação leve favorita. Este blog é escrito principalmente em Markdown, graças ao Markdown on Save Worpress Plugin. Eu ainda utilizo para escrever tutoriais simples, notas de instalação passo-a-passo, ou para guardar algumas dicas de RegEx, por exemplo.
E restructuredText pode ser utilizado com a mesma função, e graças a algumas ferramentas poderosas, é um excelente para escrever documentações longas, ou mesmo um livro (Symfony2 docs e seus livros são escritos em restructuredText).
Mas… é muito bom escrever documentação com estas linguagens de marcação, mas NÃO É tão bom ler nelas. É obrigatório convertê-las ou renderizá-las em outro formato, como HTML, ePub, PDF, etc.
Então, o que eu faço? Uso algumas ferramentas, conforme minha necessidade.
DocRenderer
https://github.com/rafaelgou/doc-renderer
Minha nova ferramenta para renderizar documentos automaticamente. O uso legal é: colocar arquivos .md e .rst num diretório web (com Apache + PHP), adicionar 3 arquivos neste diretório e tudo será renderizado com um visual do Twitter Bootstrap. Ótimo para minhas notas pessoais e referências.
Shinx-Pocoo
Esta é uma FANTÁSTICA ferramenta para renderizar documentações em restructuredText. Não apenas em HTML (e PDF, e ePub…), mas criar uma página navegável e pesquisável para a qualquer tamanho de documentação. Você certamente já viu muita documentação de software livre renderizada deste modo! Particularmente eu tenho a documentação do Symfony e Twig renderizadas localmente para referência rápida. Veja um exemplo aqui aqui.
Pandoc
http://johnmacfarlane.net/pandoc/
Por que MAIS UMA ferramenta de renderização? Bem, o Pandoc tem funcionalidades maravilhosas que o colocam no topo da minha lista. Sim, pode renderizar arquivos .md e .rst, convertê-los em muitos formatos. MAS… o mais incrível, pode converter em formatos de apresentação web como Reveal.js, DZSlides e outros! Este artigo te coloca em contato com esta idéia.
ReadTheDocs
E… dos meus bookmarks, ReadTheDocs. É um website/serviço que onde você pode colocar suas documentações para serem renderizadas com o Sphinx Pocoo. Melhor, pode sincronizar com um repositório GIT. Ainda melhor, você tem acesso ao código fonte do site e pode criar seu próprio site de documentação (na sua intranet, por exemplo).
Escrever documentação não é um esporte popular entre os desenvolvedores, mas estas ferramentas ao menos tornam isto mais divertido. Aproveite!