目次1 マークダウン (Markdown)
ガイドは GitHub Flavored Markdown で書かれています。まとまったMarkdownドキュメント、チートシート、通常のMarkdownとの違いに関する追加ドキュメント がそれぞれあります。
2 プロローグ
ガイドの冒頭には、読者の開発意欲を高めるような文を置いてください。ガイドの青い部分がこれに該当します。プロローグでは、そのガイドの概要と、ガイドで学ぶ項目について記載してください。例についてはルーティングガイドを参照してください。
3 タイトル
ガイドのタイトルにはh1、ガイドのセクションにはh2、ガイドのサブセクションにはh3をそれぞれ使用してください。なお、実際に生成されるHTMLの見出しは<h2>から始まります。
ガイドのタイトル =========== セクション ------- ### サブセクション
冠詞、前置詞、接続詞、be動詞以外の単語は冒頭を大文字にします。
#### Middlewareスタックは配列 #### オブジェクトが保存されるタイミング
通常のテキストと同じタイポグラフィを使用してください。
##### `:content_type`オプション
4 APIドキュメントの書き方
ガイドとAPIは、必要な箇所が互いに首尾一貫している必要があります。APIドキュメント作成ガイドラインの以下のセクションを参照してください
上記のガイドラインは、ガイドについても適用されます。
5 HTMLガイド
ガイドを生成する前に、システムに最新のBundlerがインストールされていることを確認してください。現時点であれば、Bundler 1.3.5がインストールされている必要があります。
最新のBundlerをインストールするにはgem install bundlerコマンドを実行してください。
5.1 生成
すべてのガイドを生成するには、cdコマンドでguidesディレクトリに移動し、bundle installを実行してから以下のいずれかを実行します。
bundle exec rake guides:generate
または
bundle exec rake guides:generate:html
my_guide.mdファイルだけを生成したい場合は環境変数ONLYに設定します。
touch my_guide.md bundle exec rake guides:generate ONLY=my_guide
デフォルトでは、変更のないガイドは生成がスキップされるので、ONLYを使用する機会はそうないと思われます。
すべてのガイドを強制的に生成するにはALL=1を指定します。
生成の際にはWARNINGS=1を指定しておくことをお勧めします。これにより、重複したIDが検出され、内部リンクが切れている場合に警告が出力されます。
英語以外の言語向けに生成を行いたい場合は、sourceディレクトリの下にたとえばsource/esのようにその言語用のディレクトリを作成し、GUIDES_LANGUAGE環境変数を設定します。
bundle exec rake guides:generate GUIDES_LANGUAGE=es
生成スクリプトの設定に使用できる環境変数をすべて知りたい場合は、単に以下を実行してください。
rake
5.2 検証
生成されたHTMLを検証するには以下を実行します。
bundle exec rake guides:validate
特に、タイトルを元にIDが生成される関係上、タイトルでの重複が生じやすくなっています。重複を検出するには、ガイド生成時にWARNINGS=1を指定してください。警告に解決方法が出力されます。
6 Kindleガイド
6.1 生成
Kindle向けにガイドを生成するには、以下のrakeタスクを実行します。
bundle exec rake guides:generate:kindle