よろしくsassdoc

@GeckoTang

sassdocとは?

Ruby製のSASSドキュメントジェネレーターです。

https://github.com/eoneill/sassdoc

何種類かあるのですが、僕は記法がjsDocToolKitに似ているeoneill/sassdocを使いました。

styleDoccoとの違い

• styleDoccoはあくまでスタイルガイドなので、jsDocToolKitなどのコードのドキュメントではありません。
• @mixinや@functionの説明をかけなくはないが、なんか見辛い。
• 自由度が低い（テンプレートのカスタマイズがしにくい）

sassdocができる事

• SASS内に書いたコメントからドキュメントを作成
• sassdoc記法にそって書いた内容が整形されて表示される
• ドキュメント内のmixinやfunctionを検索できる
• 表示する内容のフィルター出来る(mixinのみ表示、functionのみ表示）
• テンプレートがカスタマイズ出来る ( Dustjsっていうテンプレートエンジン )

こんな記法

styleDoccoとは違い、行コメントの中に独自の記法でかく

// @mixin pointer-events
// @param $value {String} [none|auto]
// @usage:
// .link.disabled{
//  =pointer-events(none);
// }
@mixin pointer-events($value:none) {
  -webkit-pointer-events: $value;
  pointer-events: $value;
}

jsDocToolKitっぽい書き方が出来ます。 （=pointer-events..と書いているのは@usageの中に@が使えない都合でSASS記法になっています）

インストール

[sudo] gem install sassdoc

ディレクトリ構成

以下の様なディレクトリ構成

┣src
┃┣ style.scss
┃┗ _mixin.scss
┗docs/

生成してみる

• src以下にあるscssをもとに、docsにドキュメントを作成します。
• ドキュメントのタイトルは俺の考えた最強のドキュメントとします。

sassdoc src -d docs -n '俺の考えた最強のドキュメント'

各オプションについてはREADMEを見てね！

生成された

┣src
┃┣ style.scss
┃┗ mixin.scss
┗docs/
　┣ css/
　┣ js/
　┣ tmpl/
　┣ index.html       #ドキュメントトップページ
　┃┣ nav.tmpl       #上部ナビゲーション
　┃┣ toc.tmpl       #左カラム
　┃┗ view.tmpl      #右カラム
　┗ sassdoc.json     #テンプレートで使用するデータ

生成されたサンプルはこちら

※sassdoc.jsonを$.getJSONしてリッチなページにしているので、サーバー上でしか動きません。

まとめ

• SASSなどのプリプロセッサでできる事が他のプログラミング言語に近づいている
• ということは、他言語のようにドキュメント作成ツールは必要
• 詳しくはソース見てね！とかは悲しい…
• 既存のテンプレはどことなく見辛いので、自分で作ったほうが良さそう。