Melhor sintaxe wiki para documentação em código Ruby e arquivos README do projeto

Question

Há alguma sintaxe wiki como rdoc, remarcação, ... recomendado no mundo do Ruby? Eu escrevo código-fonte aberto, por vezes, e não têm cola que sintaxe que eu deveria usar em documentos de código e em arquivos LEIA-ME. O que ser útil para mim que e por que você usá-lo.

Answer 1

RDoc é o instrumento de documentação padrão. A sintaxe RDoc é o padrão permitido dentro arquivos Ruby e bibliotecas.

Você pode achar texttile ou Markdown usado classes Ruby fora para arquivos de texto, como o os arquivos changelog README ou. Mas esta não é a sintaxe padrão para que você precisaria de uma maneira de dizer o analisador que sintaxe do arquivo é escrito com, geralmente desta forma é a extensão do arquivo.

GitHub, por exemplo, segue exatamente essa convecção. A menos que uma extensão .textile ou .markdown for especificado, o arquivo é analisado como RDoc.

• http://github.com/weppos/whois (.rdoc == Rdoc)
• http://github.com/rails/rails/tree/master/ railties / (sem extensão == RDOC, mas não para GitHub)
• http://github.com/technoweenie/restful-authentication /blob/master/README.textile (.textile == Têxtil)

Lembre-se:. AFAIK, documentação inline é sempre analisado como RDoc

Answer 2

Em Github, as pessoas usam principalmente Rdoc ou Textile como formato para seus LEIA-ME-arquivos. Rdoc também é muito útil para API-documentar seu código, como os integra sintaxe realmente agradáveis ??no código e é agradável de ler.