Ruby on Railsガイドライン

1 Markdown

ガイドは、GitHub Flavored Markdownで書かれています。Markdownの詳しいドキュメントやチートシートもあります。

2 プロローグ

各ガイドは、上部のモチベーションテキストで始まるべきです（それは青い領域の小さな紹介です）。プロローグは、ガイドの内容と読者が何を学ぶかを伝えるべきです。例として、ルーティングガイドを参照してください。

3 見出し

各ガイドのタイトルはh1見出しを使用し、ガイドのセクションはh2見出しを使用し、サブセクションはh3見出しを使用します。なお、生成されるHTMLの出力は<h2>から始まる見出しタグを使用します。

ガイドのタイトル
===========

セクション
-------

### サブセクション

見出しを書く際には、前置詞、接続詞、内部の冠詞、および動詞「to be」の形を除いて、すべての単語を大文字にします。

#### Assertions and Testing Jobs inside Components
#### Middleware Stack is an Array
#### When are Objects Saved?

通常のテキストと同じインラインの書式を使用します。

##### The `:content_type` Option

4 APIへのリンク

API（api.rubyonrails.org）へのリンクは、ガイドジェネレータによって以下のように処理されます。

リリースタグを含むリンクはそのままになります。例えば

https://api.rubyonrails.org/v5.0.1/classes/ActiveRecord/Attributes/ClassMethods.html

は変更されません。

リリースノートでは、対応するバージョンを指す必要があるため、これらを使用してください。

リンクにリリースタグが含まれておらず、エッジガイドが生成されている場合、ドメインはedgeapi.rubyonrails.orgに置き換えられます。例えば、

https://api.rubyonrails.org/classes/ActionDispatch/Response.html

は

https://edgeapi.rubyonrails.org/classes/ActionDispatch/Response.html

になります。

リンクにリリースタグが含まれておらず、リリースガイドが生成されている場合、Railsのバージョンが挿入されます。例えば、v5.1.0のガイドを生成している場合、リンク

https://api.rubyonrails.org/classes/ActionDispatch/Response.html

は

https://api.rubyonrails.org/v5.1.0/classes/ActionDispatch/Response.html

になります。

手動でedgeapi.rubyonrails.orgにリンクしないでください。

5 APIドキュメントのガイドライン

ガイドとAPIは、適切な場所で一貫性があるべきです。特に、APIドキュメントのガイドラインの次のセクションもガイドに適用されます。

6 HTMLガイド

ガイドを生成する前に、システムに最新バージョンのBundlerがインストールされていることを確認してください。最新バージョンのBundlerをインストールするには、gem install bundlerを実行します。

すでにBundlerがインストールされている場合は、gem update bundlerで更新できます。

6.1 生成

すべてのガイドを生成するには、guidesディレクトリに移動し、bundle installを実行してから次のコマンドを実行します。

$ bundle exec rake guides:generate

または

$ bundle exec rake guides:generate:html

生成されたHTMLファイルは./outputディレクトリにあります。

my_guide.mdのみを処理する場合は、ONLY環境変数を使用します。

$ touch my_guide.md
$ bundle exec rake guides:generate ONLY=my_guide

デフォルトでは、変更されていないガイドは処理されないため、ONLYは実際にはほとんど必要ありません。

すべてのガイドを強制的に処理するには、ALL=1を渡します。

英語以外の言語でガイドを生成したい場合は、sourceディレクトリの下に別のディレクトリ（例：source/es）を作成し、GUIDES_LANGUAGE環境変数を使用します。

$ bundle exec rake guides:generate GUIDES_LANGUAGE=es

生成スクリプトを設定するために使用できるすべての環境変数を表示するには、次のコマンドを実行します。

$ rake

6.2 検証

生成されたHTMLを次のコマンドで検証してください。

$ bundle exec rake guides:validate

特に、タイトルはその内容から生成されたIDを持つため、重複することがよくあります。

7 Kindleガイド

7.1 生成

Kindle用のガイドを生成するには、次のrakeタスクを使用します。

$ bundle exec rake guides:generate:kindle

フィードバック

このガイドの品質向上にご協力ください。

タイポや事実の誤りを見つけた場合は、ぜひ貢献してください。開始するには、ドキュメントへの貢献セクションを読んでください。

不完全なコンテンツや最新でない情報も見つかるかもしれません。メインのドキュメントに不足しているドキュメントを追加してください。修正済みかどうかは、まずEdge Guidesを確認してください。スタイルと規約については、Ruby on Rails Guides Guidelinesを確認してください。

修正すべき点を見つけたが、自分で修正できない場合は、問題を報告してください。

そして最後に、Ruby on Railsのドキュメントに関するあらゆる議論は、公式のRuby on Railsフォーラムで大歓迎です。

Chapters

フィードバック