Best ruby ​​code documentation wiki syntax and README project files

Question

Is there any wiki syntax like rdoc, markdown, ... recommended in the ruby ​​world? I sometimes write open source and don't have glue, which syntax should I use in code documents and in README files. What will be useful to me, and why you use it.

Answer 1

RDoc is the default documentation tool. RDoc syntax is enabled by default inside Ruby files and libraries.

You can find TextTile or Markdown used outside of the Ruby classes for text files, such as README or CHANGELOG files. But this is not standard syntax, so you need a way to tell the syntax where the file syntax is written, usually this path is the file extension.

GitHub, for example, follows this particular convention. If the .textile or .markdown extension is not specified, the file is parsed as an RDoc.

• http://github.com/weppos/whois (.rdoc == Rdoc)
• http://github.com/rails/rails/tree/master/railties/ (without 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 an RDoc.

Answer 2

Github Rdoc Textile README . Rdoc API- , .