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

Question

是否有任何 wiki 语法，如 rdoc、markdown、...在 ruby​​ 世界中推荐？我有时会编写开源代码，但我不知道应该在代码文档和自述文件中使用哪种语法。什么对我有帮助，你为什么使用它。

Answer 1

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

您可能会发现 TextTile 或 Markdown 在 Ruby 类之外用于文本文件，例如 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 记录代码也非常有用，因为语法很好地集成到代码中，并且易于阅读。