本ガイドは、Ruby on Railsガイドを書くためのガイドラインです。本ガイド自身が本ガイドに従って書かれており、望ましいガイドラインの例であると同時に優美なループを形成しています。
このガイドの内容:
ガイドはGitHub Flavored Markdown で書かれています。まとまったMarkdownドキュメントとチートシートがあります。
ガイドの冒頭には、読者の開発意欲を高めるような文を置いてください。ガイドの青い部分がこれに該当します。プロローグでは、そのガイドの概要と、ガイドで学ぶ項目について記載してください。例についてはルーティングガイドを参照してください。
ガイドのタイトルにはh1、ガイドのセクション見出しにはh2、ガイドのサブセクション見出しにはh3をそれぞれ使ってください。なお、実際に生成されるHTMLの見出しは<h2>から始まります。
ガイドのタイトル =========== セクション ------- ### サブセクション
冠詞、前置詞、接続詞、be動詞以外の単語は冒頭を大文字にします。
#### Middlewareスタックは配列 #### オブジェクトが保存されるタイミング
通常のテキストと同じタイポグラフィをお使いください。
##### `:content_type`オプション
NOTE、TIP、WARNINGの運用方法場合によっては、パラグラフでもう少し読者の注意を促す必要が生じることがあります（例: よくある誤解を解消する、アプリケーションを壊す可能性のある書き方などについて警告する）。
パラグラフを強調するには、以下のようにNOTE:、TIP:、WARNING:をパラグラフの冒頭に追加します。
NOTE: パラグラフの強調には、`NOTE:`、`TIP:`、`WARNING:`を使うこと。
これにより、パラグラフは以下のように専用のコンテナで囲まれるようになります。
パラグラフの強調には、NOTE:、TIP:、WARNING:を使うこと。
NOTEの運用NOTEは、主題や文脈に関連する内容を強調するのに使います。これを読むと、主題や文脈の理解や、重要な項目を明確にしたりうえで役立つようになります。
たとえば、ロケールファイルについて解説するセクションには、以下のNOTEを追加するとよいでしょう。
ロケールファイルを追加した場合は、サーバーを再起動する必要があります。
TIPの運用TIPは、主題に関する補足情報であり、必ずしも理解に関係するとは限りません。たとえば別のガイドやWebサイトを示すのに使えます。
ルーティングについて詳しくは、ルーティングガイドを参照してください。
あるいは、便利なコマンドをさらに深く掘り下げるのにも使えます。
ジェネレータのヘルプをさらに表示するには、bin/rails generate --helpを実行します。
WARNINGの運用WARNINGは、アプリケーションを壊す可能性を避けるのに使います。
コールバックメソッド内では、updateやsaveなどのメソッドや、オブジェクトに副作用を引き起こすメソッドの利用は避けること。
あるいは、アプリケーションのセキュリティを脅かす可能性のあることについて警告するのにも使えます。
アプリのマスターキーは安全に保管すること。マスターキーをリポジトリにコミットしてはいけません。
リンクの文字列には、"here"や"more"といった書き方を避け、具体的な内容のわかる文字列を使うこと。
# BAD See the Rails Internationalization (I18n) API documentation for [more details](i18n.html). # GOOD See the [Rails Internationalization (I18n) API documentation](i18n.html) for more details.
Railsガイド内の内部リンクについても同様。
# BAD We will cover this [below](#multiple-callback-conditions). # GOOD We will cover this in the [multiple callback conditions section](#multiple-callback-conditions) shown below.
APIサイト（api.rubyonrails.org）へのリンクは、以下の方法を用いてガイドのジェネレータで処理されます。
リリース番号（v5.0.1など）タグを含むリンクに対しては何も処理を行いません（例↓）。
http://api.rubyonrails.org/v5.0.1/classes/ActiveRecord/Attributes/ClassMethods.html
上は変更されません。
リリースノートではこの書式でリンクを書いてください。今後どんな対象が生成されても、リリースノートに対応したバージョンを指すようにすべきです。
リンクにリリース番号タグが含まれていない場合やedgeガイドが生成される場合は、ドメイン名の部分がedgeapi.rubyonrails.orgに置き換えられます（例↓）。
http://api.rubyonrails.org/classes/ActionDispatch/Response.html
上は以下に置き換えられます。
http://edgeapi.rubyonrails.org/classes/ActionDispatch/Response.html
リンクにリリース番号タグが含まれていない場合や、正規版のガイドが生成される場合は、Railsのバージョン番号が挿入されます。たとえば、Rails 5.1.0向けのガイドを生成すると以下のようなリンクになります。
http://api.rubyonrails.org/classes/ActionDispatch/Response.html
上は以下に置き換えられます。
http://api.rubyonrails.org/v5.1.0/classes/ActionDispatch/Response.html
edgeapi.rubyonrails.orgには手動でリンクしないでください。
古いガイドの行を折り返すためだけの目的で再フォーマットしないでください。ただし、新しいセクションとガイドは80文字目で折り返す必要があります。
ガイドとAPIは、必要な箇所が互いに首尾一貫している必要があります。APIドキュメント作成ガイドラインの以下のセクションを参照してください
上記のガイドラインは、ガイドについても適用されます。
ガイドを生成する前に、システムに最新のBundlerがインストールされていることを確認してください。最新のBundlerをインストールするにはgem install bundlerコマンドを実行してください。
Bundlerを既にインストールしている場合は、gem update bundlerで最新のBundlerに更新できます。
すべてのガイドを生成するには、cdコマンドで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
生成されたHTMLをバリデーション（検証）するには以下を実行します。
$ bundle exec rake guides:validate
特に、タイトルを元にIDが生成される関係上、タイトルでの重複が生じやすくなっています。
Kindle向けにガイドを生成するには、以下のrakeタスクを実行します。
$ bundle exec rake guides:generate:kindle
Railsガイドは GitHub の yasslab/railsguides.jp で管理・公開されております。本ガイドを読んで気になる文章や間違ったコードを見かけたら、気軽に Pull Request を出して頂けると嬉しいです。Pull Request の送り方については GitHub の README をご参照ください。
原著における間違いを見つけたら『Rails のドキュメントに貢献する』を参考にしながらぜひ Rails コミュニティに貢献してみてください 🛠💨✨
本ガイドの品質向上に向けて、皆さまのご協力が得られれば嬉しいです。
Railsガイド運営チーム (@RailsGuidesJP)
Railsガイドは下記の協賛企業から継続的な支援を受けています。支援・協賛にご興味あれば協賛プランからお問い合わせいただけると嬉しいです。
