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

Question

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

Answer 1

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

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

例如，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 == 纺织品)

记住:据我所知，内联文档总是被解析为 RDoc。