この記事は
たちくらが
に
書きました。

バブル全盛期の六本木でお仕事→ワーキングホリデー→海外をサーフィンしながら転々。→飲食店→土地開発コンサル会社→鉄鋼メーカー→大学でお勉強→システムエンジニア→Webのお仕事→フリーランス→食品メーカー→次へ。 ほぼ好奇心で生きていますが、転職・海外・波乗り・情報収集経験は人より多めです。

Javadocみたいなスタイルガイドジェネレーター「styleDocco」の使い方とgruntで自動化（node.jsインストール）

LINEで送る
Pocket
このエントリーをはてなブックマークに追加

CSSジェネレーター・プリプロセッサ

Webサイト制作を一人で全てやってしまう時は必要ないんですけど、ディレクターやUI/UXデザイナー、フロントエンドなど複数人がかかわる案件などでは、割と早い段階で見出しやリスト等のデザインが可視化できるのは、どのフェーズの人にとってもありがたいです。
きっと開発効率が上がる・・・はずですw。
特にクライアントにとってスタイルガイドは、ブラウザ上で見れると非常にイメージがわきやすく、制作側とのイメージが乖離するといったリスクを減らすこともできます。
そのために「styleDocco」を使うことは非常に有効かつ開発効率も上がるかと思います。
また、gruntを使ってスタイルガイドのページを自動生成する方法も後述しますが、gruntを使うことでlessなどのCSSプリプロセッサのコンパイルもできて色々と拡張実装できます。

「styleDocco」とはJavaプログラマーはJavadocをイメージしてもらうとわかりやすいかと思います。
CSSを記述する時に「styleDocco」で決められている形式でコメントを入れると、アノテーション（あくまで注釈）を入れてスタイルガイドとしてブラウザ表示できるようにHTMLファイルを吐き出してくれます。
「styleDocco」の他にも「Kalei」や「KSS-node」、「KSS」などがあります。

「styleDocco」を利用する準備

1. まず、PCに実装して利用するために準備するものがあります。

  • node.js
  • npm（Node Package Manager、node.jsのパッケージマネージャー、Javaでいうmavenのxmlみたいにjsonでセットアップファイルを作れます）

「styleDocco」自体は「node.js」上で動きますが、その「node.js」で利用するパッケージマネージャーの「npm」をマシン上にインストールする必要があります。
「node.js」の本家サイトnode.js（http://nodejs.org/download/）へ行き、Windows版は適宜32bit版か64bit版を選択してダウンロード後、インストールしてください。
Macの方は.pkgの最新版をダウンロード後、ダブルクリックしてインストールを実行しちゃってください。

styleDoccoのインストール

nodeのインストーラー画面

インストーラーを実行すれば、「node.js」「npm」共にインストールされます。
ターミナルを起動して、以下のコマンド実行後に各バージョンが表示されればインストールが完了してます。

~$ node –v
~$ npm –v

ターミナルのキャプチャ

続いてターミナルから下記のコマンドを実行して「styleDocco」のインストールを実行します。
ただし、ここはsudoで実行してください。お使いのマシンの管理者権限（パスワード）が必要になります。

~$ su
Password:
~$ npm install –g styledocco

styledoccoをターミナルからインストール

以上で準備作業は完了です。

「styleDocco」を使ってみる

まず、生成元となるCSSファイルを置く場所としてフォルダを作ります。
これは任意の場所でよいですが、僕は生成されたファイルをすぐブラウザで見たいので、XAMPPのドキュメントルートディレクトリ内に階層を掘って“doccotest”というプロジェクトフォルダを作成・配置しました。
そうすれば生成後に、http://localhost/doccotest/docs/style.htmlみたいなアドレスでソッコー確認することができちゃいます。

上記で作った“doccotest”内に“css”フォルダを作り、その中に“style.css”を作って下記を記述します。

@charset "utf-8";
/*
# 見出しのスタイル

基本となるクラスは'.hbase'

＜h＞タグ以外の小見出しは２タイプ

```
<h1 class="hbase">スタイルガイドh1</h1>
<h2 class="hbase">スタイルガイドh2</h2>
<h3 class="hbase">スタイルガイドh3</h3>
<div class="hbase htype1">
  <p>小見出しtype1</p>
</div>
<div class="hbase htype2">
  <p>小見出しtype2</p>
</div>
```
*/

.hbase {
  padding: 5px 0;
  width: 100%;
}
.htype1{
	color:#FFF;
	background-color:#666;
}
.htype2{
	border:1px solid #666;
	color:#666;
}

そして、ターミナルでターゲットのディレクトリに移動してからコマンドを実行します。

~$ cd（ディレクトリへのパス）/doccotest ~$ styledocco -n "Style Guide" css/style.css

最初に作成した“css”ディレクトリと同階層に“docs”フォルダ、さらにその中にindex.html、style.htmlができていれば成功です。

コマンド実行時のオプションは以下の通りです。
-nオプションで渡している「Style Guide」はプロジェクト名となり、同時に生成されるindex.htmlへのリンク文字になります。
他に渡せるオプションは、以下の通りです。

  • -n・・・ プロジェクト名となり、生成後表示されるページのindex.htmlへのリンクとなります。
  • -o ・・・ アウトプット先ディレクトリ（デフォルトでは“docs”になります。 ）
  • –preprocessor ・・・ プリプロセッサを使用する場合、対象の名称をいれます（例：”sass”）
  • –include ・・・ プレビュー時に他のCSSやjsファイルなんかを同時に呼び込む際に使用する
  • –verbose ・・・ コマンド実行時にログを出力する（デフォルトは非表示）

その他、style.cssのMarkdown記法など

説明書きのタイトル

生成されたstyle.html内でスタイルの説明書きにタイトル、見出しとして表示するには「#」を使用します。
「#」一つの行があると意味的にはh1となり、一要素のセクションとして区切る事ができます。

# 小見出し
## タイプ01
## タイプ02

HTMLソース部分

なぜか入力しづらい「`（バックティック）」を多用します。
htmlソースは、前後を３つのバックティックで囲みます。

```
<div class=”hoge” >
  <p>FUGAFUGA</p>
</div>
```

強調したい文字列、クラス名など

強調表示したいクラス名などは「`（バックティック）」一個で囲みます。

`.hogeclass`

index.htmlファイルについて

生成時にはアクセスすると、作成した内容については何も書かれてません。
ここに表示させるためにはマニュアルで「README.md」というファイルを作り、style.cssと同じcssディレクトリ内に配置します。
記法はstyle.cssと同じMarkdown記法を用いますが、「/*〜*/」はいりません。
ここにスタイルガイドの目次的な説明をいれておくと後々役にたつ・・・場合も。

README.md
# 見出しのスタイルとは
##説明１

1番の説明書き`.hoge`

##説明２

２番の説明書き`.fuga`

```
<h3 class=”hoge”></h3>
<h3 class=”fuga”></h3>

```

style.cssドキュメント内のコメントアウト

スタイル以外のテキストやhtmlソースなどは「/*〜*/」で囲みますが、CSSドキュメント内だけのコメントアウトを作りたい場合は、開始の「/*」前に半角スペースをいれると、style.css内のみのコメントアウトとなります。

/* これは反映されます。 */
 /* これは反映されないコメントアウトです。 */

style.cssファイル更新と同時に反映（htmlファイル生成）させる方法

gruntのwebサイト
GRUNTのwebサイト

上記で説明してきた内容で使用している場合、style.cssファイルを更新するたびにstyledoccoコマンドを実行しないとhtmlは生成されません。
そこで、「grunt」を使用して更新と同時に動的に生成・更新してくれる方法を追加したいと思います。
そして同時にWebサイト表示の高速化のためにminfyされたCSSも吐き出しちゃいます。

「grunt-cli」をインストール

ターミナルから以下を実行して、インストール実行して確認します。
「-g」はオプションで、グローバルインストールの意味です。これはスーパーユーザー（sudo）で実行してください。

# npm install –g grunt-cli
# grunt --version
# （インストールしたバージョンが表示される）

ここで、『grunt –version』を実行しても『# grunt: command not found』が返ってきてしまう場合はインストールが失敗していたり、古いバージョンのgruntがインストールされている可能性があります。
下記のように一度アンインストールして『grunt-cli』で再度インストールしてみましょう。

# npm uninstall –g  grunt
# npm install –g grunt-cli

「grunt」は0.4へのバージョンアップの際に大幅な仕様変更がありました。
そのため、古いバージョンは必ずアンインストールしましょう。

上記が完了しても、コマンドが使えるようになるだけでgrunt本体はまだインストールされていません。
ターミナル上では一旦exitコマンドで自分のユーザーに戻ります。

grunt本体のインストール

gruntはプロジェクトフォルダごとにプラグインのパッケージをインストールできます。
プロジェクトごとに管理した方がバージョンの違いによる問題などが起きにくいと思います。
方法は二つあり、「package.json」ファイルを使う方法と、コマンドラインからサクッと入れる方法です。

1.「package.json」を作成してインストールを実行する方法
インストールしたいプラグインを「package.json」に記述し、プロジェクトフォルダ内に配置します。

・ 「package.json」の内容

{
  "author": "Atsushi Hiruta",
  "name": "FirstProject",
  "version": "1.0.0",
  "description": "",
  "devDependencies": {
    "grunt": "~0.4.1",
    "grunt-contrib": "",
    "grunt-styleguide": "~0.2.1"
  }
}

続いて、ターミナルからインストールを実行します。
プロジェクトファイルに移動してから下記を実行します。

~$ nmp install

実行すると、プロジェクトフォルダ内に「node_modules」フォルダが作られて各モジュールが配置されます。

2. gruntコマンドを打ってサクッと入れる

~$ npm install grunt
~$ npm install grunt-contrib
~$ npm install grunt-styleguide

最後のgrunt-styleguideを実行したところ・・・エラー！
grunt-contribまではすんなり入るのですが、grunt-styleguideでエラーが出ました。macのOSバージョンによっては入らない様です。
以下のようなエラーが出力されました。

npm ERR! Error: ENOENT, lstat '/パス /node_modules/grunt-styleguide/node_modules/stylus/lib/nodes/keyframes.js'
npm ERR! If you need help, you may report this *entire* log,
npm ERR! including the npm and node versions, at:
npm ERR!     <http://github.com/isaacs/npm/issues>

npm ERR! System Darwin 10.8.0
npm ERR! command "node" "/usr/local/bin/npm" "install" "grunt-styleguide"
npm ERR! cwd /
npm ERR! node -v v0.10.25
npm ERR! npm -v 1.3.24
npm ERR! path /パス/node_modules/grunt-styleguide/node_modules/stylus/lib/nodes/keyframes.js
npm ERR! fstream_path

これはgruntがバージョンアップ後、grunt-styleguide自体がnpmに未対応のためかgitから落とさなければならなくなっていることが原因のようです。
Macの場合、Xcodeのコマンド実行機能を利用するためにXcodeをインストールする必要がありますが、SnowLeopardあたりのバージョンでは最新のXcodeはダウンロードできません。
その際の対処としては、まずOSのバージョンを10.8.4以上にします。MountainLionですかね？

xcode

Mac OSの環境が整ったら、Xcodeをインストールしてください。
インストールが完了したらXcodeを起動し、メニューから[Xcode] – [Preferences]をクリックします。

xcodeのメニューから

開いたダイアログの[Downloads]タブ内の[Components]から[Command Line Tools]にチェックを入れてインストールを実行してください。

commandinstallを選択インストール実行

インストール完了後、再びターミナルでプロジェクトディレクトリに戻って以下を実行してください。

~$ npm install grunt-styleguide –save-dev

するとエラーなくgrunt-styleguideがインストールできるかと思います。

Gruntfile.jsファイルを作る

インストールしたプラグインはそのままでは動かないので、Gruntfile.jsファイルを作って「loadNpmTasks」メソッドで呼び出します。
既に上記で説明してきた“doccotest”というプロジェクトフォルダを利用します。
“doccotest”プロジェクトフォルダ直下にGruntfile.jsファイルを配置します。

・ Gruntfile.jsの内容は以下の通り。

module.exports = function(grunt) {
  grunt.initConfig({
    cssmin: {
      compress: {
        files: {
          'css/style-min.css': 'css/style.css'
        }
      }
    },
    styleguide: {
      styledocco: {
        options: {
          framework: {
            name: 'styledocco'
          },
          name: 'Test Project',
          template: {
            include: ['plugin.css', 'app.js']
          }
        },
        files: {
          'docs': 'css/style.css'
        },
      }
    },
    watch: {
      files: ['css/*.css'],
      tasks: ['cssmin', 'styleguide']
    }
  });
  //以下で呼び出し
  grunt.loadNpmTasks('grunt-contrib-cssmin');
  grunt.loadNpmTasks(‘grunt-styleguide’);
  grunt.loadNpmTasks(‘grunt-contrib-watch’);
  
};

Gruntfile.jsをプロジェクトディレクトリに配置して、以下を実行すると待ち状態になります。

~$ grunt watch
Running "watch" task
Waiting...

この状態でcss/style.cssを上書きするなり、command+sで保存したりすると自動的にHTMLファイルが更新されます。

以上でgruntを使った自動更新作業は完了となります。

いつも読んでくれてありがとね！
LINEで送る
Pocket
このエントリーをはてなブックマークに追加

この記事のカテゴリーは『 IT & Web Design 』です。

たちくら

バブル全盛期の六本木でお仕事→ワーキングホリデー→海外をサーフィンしながら転々→飲食店→土地開発コンサル会社→鉄鋼メーカー→大学でお勉強→システムエンジニア→Webのお仕事→フリーランス→食品メーカー→次へ。 ほぼ好奇心で生きていますが、転職・海外・波乗り・情報収集経験は人より多めです。

PAGE TOP