Ruby コードとプロジェクトの README ファイルのドキュメントに最適な Wiki 構文

Question

rdoc、マークダウンなどの Wiki 構文はありますか?Rubyの世界では推奨されていますか？私は時々オープン ソース コードを書きますが、コード ドキュメントや README ファイルでどの構文を使用すればよいのかわかりません。それを使用する理由と、それを使用する理由。

Answer 1

RDoc はデフォルトのドキュメント ツールです。RDoc 構文は、Ruby ファイルおよびライブラリ内で許可されるデフォルトの構文です。

README や CHANGELOG ファイルなどのテキスト ファイルの Ruby クラスの外で TextTile または Markdown が使用されていることがあります。ただし、これは標準の構文ではないため、ファイルがどの構文で記述されているかをパーサーに伝える方法が必要になります。通常、この方法はファイル拡張子です。

たとえば、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 として解析されます。

Answer 2

のGithub上で、人々はほとんど自分のREADME-ファイルのフォーマットとしてのRDocやテキスタイルを使用します。構文はコードに本当に素敵統合し、読むことが楽しいようRDOCは、また、API-文書化してコードのために非常に便利です。