Ruby: Slate で API ドキュメントを書く

Ruby ほぼ関係ないですが、Ruby で作成されたドキュメントツールということで。

Slate はマークダウンから素敵 API ドキュメントを生成できるスタティックサイトジェネレーターの一種。
stripe.comPaypal の API ドキュメントを参考にデザインされていて、
サンプルサイトのような感じのものが出力できます。

Slate

手順

1. https://github.com/tripit/slate のリポジトリをフォークする
2. 自分のリポジトリにできた slate を git clone https://github.com/YOURUSERNAME/slate.git
3. cd slate から bundle install
4. bundle exec middleman server

これで localhost:4567 で起動される。

source 下の index.md マークダウンファイルを書き換えると、ドキュメントが更新されます。

.
├── CHANGELOG.md
├── CONTRIBUTING.md
├── Gemfile
├── Gemfile.lock
├── LICENSE
├── README.md
├── Rakefile
├── config.rb
├── lib
│   └── redcarpet_header_fix.rb
└── source
    ├── fonts
    │   ├── icomoon.eot
    │   ├── icomoon.svg
    │   ├── icomoon.ttf
    │   └── icomoon.woff
    ├── images
    │   ├── logo.png
    │   └── navbar.png
    ├── includes
    │   └── _errors.md
    ├── index.md
    ├── javascripts
    │   ├── all.js
    │   ├── all_nosearch.js
    │   ├── app
    │   │   ├── lang.js
    │   │   ├── search.js
    │   │   └── toc.js
    │   └── lib
    │       ├── energize.js
    │       ├── jquery.highlight.js
    │       ├── jquery.tocify.js
    │       ├── jquery_ui.js
    │       └── lunr.js
    ├── layouts
    │   └── layout.erb
    └── stylesheets
        ├── icon-font.scss
        ├── normalize.css
        ├── print.css.scss
        ├── screen.css.scss
        ├── syntax.css.scss.erb
        └── variables.scss

include を使って index.md を分割する事ができます。
Using Include

ルートで以下を実行すると、build ディレクトリができて、スタティックな html サイトを生成する事ができます。

$ rake build .
build
├── fonts
│   ├── icomoon.eot
│   ├── icomoon.svg
│   ├── icomoon.ttf
│   └── icomoon.woff
├── images
│   ├── logo.png
│   └── navbar.png
├── index.html
├── javascripts
│   ├── all.js
│   ├── all_nosearch.js
│   ├── app
│   │   ├── lang.js
│   │   ├── search.js
│   │   └── toc.js
│   └── lib
│       ├── energize.js
│       ├── jquery.highlight.js
│       ├── jquery.tocify.js
│       ├── jquery_ui.js
│       └── lunr.js
└── stylesheets
    ├── icon-font.css
    ├── normalize.css
    ├── print.css
    ├── screen.css
    ├── syntax.css
    └── variables.css

これを適当なウェブサーバーにアップロードするのもよいですし、

フォークしたレポジトリをベースにして github page をデプロイ先にするのも良いでしょう。
Deplying Slate