スタイルガイドについて

ざっくり言うとスタイルシートのドキュメントです。

自分一人で完結するその場限りのページなら良いのですが、 複数人のチームで組み込んでいたり、メンテナンス担当が他の方だったりする場合、 プロジェクトのCSSをドキュメント化しておく必要が出てきますね。例えば、

• どのような命名規則や方針で書かれていて
• どこになにがあり
• どのようなモジュールがどこで使えて
• そのモジュールはどうするとどのような挙動を起こすのか

等をまとめておく文書になると思います。 規模によってはかなり骨な作業になりそうです。

StyleDoccoとは

• StyleDocco

StyleDocco generates documentation and style guide documents from your stylesheets.

スタイルシートを読み込んで、自動的にドキュメンテーションを生成してくれるツールです。

その為の記法に従う必要がありますが、 基本的にはCSSの記述の前に、コメント（ /* */ )で、概要文とプレビュー用のHTMLを書くだけです。 もちろんそのままCSSとしても機能します。

インストール

早速インストールをしてみます。 node.jsで動作するので、先に導入しておきましょう。

node.jsが入ったら、npmコマンドを叩くだけです。
※環境によってはsudoや管理者権限が必要だったりします。

$ npm install -g styledocco

使い方

CSSの書き方

前述の通り、ドキュメントの生成にはその為の記法に従う必要があります。

/*
# ボタン

基本的なボタンスタイル。

    <button class="button">ボタン</button>

*/

.button {
    border-radius:4px;
    border:1px solid #ccc;
    background-color:#f9f9f9;
}

• 概要文はMarkdown記法に対応しています。
• プレビュー用のHTMLにはインデントが必要です。
  
  （タブでもいけましたが、一応公式によれば4スペースとの事です。）

生成コマンド

インストールすると styledocco コマンドが使用出来るようになります。 以下は、「css」ディレクトリの中のファイルを元にドキュメントを生成する例。 出力先はデフォルトで「docs」ディレクトリになります。

$ styledocco -n "My Project" css

使いそうな引数オプションはここらへんでしょうか。

• –name -n プロジェクト名（ドキュメントタイトルになります）
• –out -o 出力ディレクトリ（デフォルトはdocs）
• –preprocessor 使用するプリプロセッサ（Sassとかlessのコマンドを渡します）

例えば以下は「My Project」というタイトルで、「styles」フォルダのソースを元に「mydocs」へ出力をし、 プリプロセッサには「lessc」コマンドを使用する事になります。

styledocco -n "My Project" -o mydocs --preprocessor "lessc" styles

cf) StyleDocco – Usage

gruntで自動化など

gruntでwatchして自動化したい場合は、grunt-styleguide等を利用します。 （諸事情により私は使いませんでした）

• indieisaconcept/grunt-styleguide · GitHub

あるいは grunt-shell でシェルコマンドを書いたり、 自分でタスクを書くなどして、うまいこと楽をすると良いでしょう。

その他、細かい使用感など

ページのはじめに謎の空白のボックスが？

ちょっとハマった箇所ですが、ページの一番はじめのセクションで謎の空白ボックスが生まれてしまいました。

概要文のコメントの先頭に改行を挟んでしまうとこうなります。

/*

# これはダメ



/*
# こうしましょう

プレビューHTML前の改行

概要文とHTMLの間は基本的に1行空いていればいいのですが、 概要文がMarkdownのリスト等になっている様な場合は2行以上あけないとプレビューが正常に表示されません。

/*
# ボタン

* リスト
* リスト


    <!--こういったケースは2行あけましょう。-->

プリコンパイラも併せて使うと重たい？

私の携わったプロジェクトではSass+bootstrapで実装をしていた為、 Sassの重さとbootstrapのボリュームが相まってcss自体のジェネレートに少々時間を要しました。 それに加えて、StyleDoccoのドキュメント生成もある程度時間がかかるため、合わせ技で相当遅くなります。 gruntで自動化をしなかったのはその為です。

ただ、ファイル数やボリュームにも因る所が大きいので一概には言えません。 また、逆に最適化をする機会にも繋がるとも言えますね。

ナビゲーションの生成について

ドキュメントのヘッダナビゲーションには、 スタイルシートのファイル毎にメニューが生成されます。 また、フォルダでファイルを分けている場合は、プルダウンメニューになります。

例えばこのような構造にしてあった場合

css/
  ├ common/
  │   ├ foo.css
  │   ├ bar.css
  │   └ baz.css
  ├ components/
  ├ widgets/
  └ README.md

このような感じに出力されます。

ただし、Macでは問題なかったのですが、当方のWindows環境ではサブフォルダを全て無視されてしまいました。 Issueに投げてみたので、何か反応があったらお伝えします。

ドキュメントページのパフォーマンス

生成されたドキュメントページで動作がもたつくな、と感じたので中身をみてみました。

StyleDoccoのドキュメントページは、ページ毎にひとつのHTMLになっています。 CSSやJavaScriptなどの外部リソースはありません。完全にひとつのファイルです。

プレビューの出力はどうやっているのかというと

1. iframeを動的に生成して、そこに自分自身を読み込む
2. 読まれたHTMLでプレビューを生成し、描画する

という処理をHTMLファイルに記述されたJavaScriptで行なっているようです。

JSで動的に生成している関係上、物とボリュームによっては描画や目次の生成などの動作がもたつく場合があります。 が、「単一ファイルでいきたい！！」というポリシーがひしひしと伝わってくるので、これはこういう物だと思って割り切りました。

まとめ

自前のテンプレートでスタイルガイドを書く手もありますが、 うまく用途にマッチするのであれば、こういうツールを使って楽をしていきたいですね。