Miglior sintassi wiki per la documentazione nel codice ruby ​​e file README di progetto

Question

Ci sono delle sintassi wiki come rdoc, Markdown, ... raccomandato nel mondo Ruby? Ho scrivere codice open source a volte e non hanno alcun collante che la sintassi dovrei usare nei documenti di codice e nel file README. Quello che essere utile per me, che e perché lo si utilizza.

Answer 1

RDoc è lo strumento di documentazione di default. La sintassi RDoc è quella predefinita consentita all'interno di file di Ruby e librerie.

Si potrebbe trovare texttile o Markdown utilizzate al di fuori classi di Ruby per file di testo come ad esempio il file README o CHANGELOG. Ma questa non è la sintassi standard in modo che si avrebbe bisogno di un modo per dire al parser, che la sintassi file viene scritto con, di solito in questo modo è l'estensione del file.

GitHub, per esempio, segue esattamente questo convenction. A meno che non sia specificato un'estensione .textile o .markdown, il file viene analizzato come RDoc.

• http://github.com/weppos/whois (.rdoc == rdoc)
• http://github.com/rails/rails/tree/master/ railties / (senza estensione == rdoc, ma non per GitHub)
• http://github.com/technoweenie/restful-authentication /blob/master/README.textile (.textile == tessile)

Ricorda: per quanto ne so, la documentazione in linea è sempre analizzato come RDoc

.

Answer 2

su GitHub, le persone usano per lo più rdoc o tessile come formato per i loro README-files. Rdoc è anche molto utile per API-documentare il codice, come la sintassi si integra davvero bello nel codice ed è piacevole da leggere.