Best wiki syntax for documentation in ruby code and project README files

Question

Hi,

Are there any wiki syntax like rdoc, markdown, ... recommended in the ruby world? I write sometimes open source code and have no glue which syntax I should use in Code documents and in README files. What be helpful for me which and why you use it.

Answer 1

I see lots of YAML and HAML in the Ruby world but I'm not sure it there's a set default for such stuff. I personally like YAML because it's very simple but enough powerful to structure all kinds of information. I even use a YAML like syntax for taking notes on paper. :)

Answer 2

On Github, people mostly use Rdoc or Textile as format for their README-files. Rdoc is also very useful for API-documenting your code, as the syntax integrates really nice into the code and is pleasant to read.

Answer 3

RDoc is the default documentation tool. The RDoc syntax is the default one allowed inside Ruby files and libraries.

You might find TextTile or Markdown used outside Ruby classes for text files such as the README or the CHANGELOG files. But this isn't the standard sintax so you would need a way to tell the parser which syntax the file is written with, usually this way is the file extension.

GitHub, for example, follows exactly this convenction. Unless a .textile or .markdown extension is specified, the file is parsed as RDoc.

• http://github.com/weppos/whois (.rdoc == Rdoc)
• http://github.com/rails/rails/tree/master/railties/ (no extension == Rdoc, but not for GitHub)
• http://github.com/technoweenie/restful-authentication/blob/master/README.textile (.textile == Textile)

Remember: AFAIK, inline documentation is always parsed as RDoc.