Meilleure syntaxe wiki pour la documentation dans le code Ruby et projet fichiers README

Question

Y a-t-il une syntaxe wiki comme rdoc, démarquage, ... recommandé dans le monde Ruby? J'écris parfois du code open source et dépourvues de colle qui syntaxe je devrais utiliser dans les documents de code et dans les fichiers README. Ce qui est utile pour moi qui et pourquoi vous l'utilisez.

Answer 1

RDoc est l'outil de documentation par défaut. La syntaxe RDoc est celui par défaut autorisé dans les fichiers Ruby et les bibliothèques.

Vous trouverez peut-être TextTile ou Markdown utilisés en dehors des classes Ruby pour les fichiers texte tels que le README ou les fichiers changelog. Mais ce n'est pas SINTAX standard, donc vous auriez besoin d'un moyen de dire l'analyseur qui syntaxe du fichier est écrit avec, le plus souvent de cette façon est l'extension du fichier.

GitHub, par exemple, suit exactement ce Convenction. À moins d'une extension .textile ou .markdown est spécifié, le fichier est analysé comme RDoc.

(.Rdoc == RDoc)
• http://github.com/weppos/whois
• http://github.com/rails/rails/tree/master/ railties / (pas d'extension == rdoc, mais pas pour GitHub)
• http://github.com/technoweenie/restful-authentication /blob/master/README.textile (.textile == Textile)

Rappelez-vous: AFAIK, la documentation en ligne est toujours analysée comme RDoc

.

Answer 2

Sur Github, les gens utilisent la plupart du temps rdoc ou textile comme format pour leurs fichiers README. Rdoc est également très utile pour API documenter votre code, comme la syntaxe intègre vraiment bien dans le code et est agréable à lire.