ruby代码和项目自述文件中的文档的最佳wiki语法

Question

在ruby世界中推荐使用rdoc，markdown等的wiki语法吗？ 我有时会编写开源代码，并且没有粘合剂，我应该在Code文档和README文件中使用哪种语法。什么对我有用以及为什么使用它。

Answer 1

RDoc是默认的文档工具。 RDoc语法是Ruby文件和库中允许的默认语法。

您可能会发现在Ruby类之外使用TextTile或Markdown来处理文本文件，例如README或CHANGELOG文件。但这不是标准的sintax所以你需要一种方法来告诉解析器文件的编写语法，通常这种方式是文件扩展名。

例如，GitHub正好遵循这一惯例。除非指定了.textile或.markdown扩展名，否则该文件将被解析为RDoc。

• http://github.com/weppos/whois（.rdoc == Rdoc）
• http://github.com/rails/rails/tree/master/railties/（没有扩展名== Rdoc，但不适用于GitHub）
• http://github.com/technoweenie/restful-authentication/blob/master/README.textile（。textile == Textile）

请记住：AFAIK，内联文档始终被解析为RDoc。

Answer 2

在Github上，人们大多使用Rdoc或Textile作为其README文件的格式。 Rdoc对于API代码编写也非常有用，因为语法非常适合代码并且阅读起来很愉快。