Rails ガイドのガイドライン

本ガイドは、Ruby on Railsガイドを書くためのガイドラインです。本ガイド自身が本ガイドに従って書かれており、望ましいガイドラインの例であると同時に優美なループを形成しています。

このガイドの内容:

Railsドキュメントの記法

ガイドをローカルで生成する方法

1 マークダウン (Markdown)

ガイドは GitHub Flavored Markdown で書かれています。まとまったMarkdownドキュメント、チートシート、通常のMarkdownとの違いに関する追加ドキュメントがそれぞれあります。

2 プロローグ

ガイドの冒頭には、読者の開発意欲を高めるような文を置いてください。ガイドの青い部分がこれに該当します。プロローグでは、そのガイドの概要と、ガイドで学ぶ項目について記載してください。例についてはルーティングガイドを参照してください。

3 タイトル

ガイドのタイトルにはh1、ガイドのセクションにはh2、ガイドのサブセクションにはh3をそれぞれ使用してください。なお、実際に生成されるHTMLの見出しは<h2>から始まります。

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

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

### サブセクション

冠詞、前置詞、接続詞、be動詞以外の単語は冒頭を大文字にします。

#### Middlewareスタックは配列
#### オブジェクトが保存されるタイミング

通常のテキストと同じタイポグラフィを使用してください。

##### `:content_type`オプション

4 APIにリンクする

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には手動でリンクしないでください。

5 APIドキュメントの書き方

ガイドとAPIは、必要な箇所が互いに首尾一貫している必要があります。APIドキュメント作成ガイドラインの以下のセクションを参照してください

上記のガイドラインは、ガイドについても適用されます。

6 HTMLガイド

ガイドを生成する前に、システムに最新のBundlerがインストールされていることを確認してください。現時点であれば、Bundler 1.3.5以降がインストールされている必要があります。

最新のBundlerをインストールするにはgem install bundlerコマンドを実行してください。

6.1 生成

すべてのガイドを生成するには、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

6.2 検証

生成されたHTMLを検証するには以下を実行します。

bundle exec rake guides:validate

特に、タイトルを元にIDが生成される関係上、タイトルでの重複が生じやすくなっています。重複を検出するには、ガイド生成時にWARNINGS=1を指定してください。警告に解決方法が出力されます。

7 Kindleガイド

7.1 生成

Kindle向けにガイドを生成するには、以下のrakeタスクを実行します。

bundle exec rake guides:generate:kindle

railsguides.jp