Grunt × SCSS × Compass × StyleDocco（Bundler使ってインストール版）


# 前書き

[前回の記事](http://qiita.com/youkaiantena/items/59459a2d447ad739ddfc)を投稿したら、

「何で`Bundler`入ってんのに、`sudo gem`とかやってんすか？？意味が分かりません。大体、そんな情報をWebに流すとか(ry」

と叱られたので、Bundler使ってるバージョンを、、、

# 情報

## 環境

|name|version|
|:--|--:|
|Mac OS X|10.9.3|
|Bundler|1.6.0|
|Sass|3.2.19|
|Compass|0.12.6|
|StyleDocco|0.6.6|
|Node.js|0.10.28|
|npm|1.4.13|
|grunt|0.4.5|
|grunt-cli|0.1.13|
|grunt-contrib-compass|0.8.0|
|grunt-styledocco|0.1.4|
|grunt-este-watch|0.1.16|

## 参考にした情報

[Compass環境の構築](http://qiita.com/u-minor/items/47194a0b3d724e2fd27c)
https://gist.github.com/geckotang/6332562

## 構造

*全ての作業が終わると、下記の様な構造になります。*

develop
　|--grunt
　　|--Gemfile
　　|--Gemfile.lock
　　|--grunt-test
　　　|--Gruntfile.js
　　　|--config.rb
　　　|--node_modules
　　　|--package.json
　　　|--scss
　　　|--assets
　　　　|--css
　　　　|--images
　　　　|--js
　　　|--docs
　　　　|--styleguide
　　|--vendor
　　　|--bundle

# 開発環境構築手順

*`Node.js`, `npm`, `Bundler`はインストール済みである事を前提に進めます。*

## "Node.js"のインストール

省略

## "npm"のインストール

省略

## "Bundler"のインストール

省略

## "Sass", "Compass"のインストール

ここで`Bundler`を使用します。
※前回、`Sass v3.3.8`を使用しましたが、2014年6月8日現在、Bundlerを使用してインストールできるバージョンは`Sass v3.2.19`になります。

### "Gemfile"の作成
```bash:bash
$ cd ~/develop/grunt
$ bundle init
```
これで現在のディレクトリー配下に`Gemfile`が生成されます。

### "Gemfile"の編集

*今回は、上書きしました。*

```Gemfile:~/develop/grunt/Gemfile
# A sample Gemfile
source "https://rubygems.org"

gem "sass", "~> 3.2.19"
gem "compass", "~> 0.12.6"
```

### "Sass", "Compass"のインストール

`develop/grunt`ディレクトリーにて、`bundle install`を実行します。
`--path`オプションを使用し、`develop/grunt/vendor/bundle`にgemがインストールされる様にします。

```bash:bash
$ bundle install --path vendor/bundle
```

## "Compass"

### "Compassプロジェクト"の作成

`Compass`のインストールは完了しているので、早速Compassプロジェクトを作成します。
Bundlerを使用したインストールを行っているため、`bundle exec compass create`といった形式で実行する必要があります。
*尚、`bundle exec`を頭につけない方法もありますが、これについては他の方が書かれている記事を参考にしてください。*

```bash:bash
$ cd ~/develop/grunt

# compassプロジェクトを作成します。
$ bundle exec compass create grunt-test

# stylesheetsというディレクトリーが生成されますが、今回は不要なので削除します。
$ rm -R grunt-test/stylesheets

# sassというディレクトリーが生成されますが、今回はscssなのでリネームします。
$ mv grunt-test/sass grunt-test/scss
```

### "config.rb"の修正

```ruby:config.rb
http_path = "/"
# SCSS(Sass)ファイルの置き場所
sass_dir = "scss"
# コンパイルのCSSファイルの置き場所
css_dir = (environment == :production) ? "assets/css" : "docs/css"
# 画像ファイルの置き場所
images_dir = "assets/images"
# JavaScriptの置き場所
javascripts_dir = "assets/js"
# CSSの出力方法
output_style = (environment == :production) ? :compressed : :expanded
# 既存のファイルを上書きするか否か
force = true 
# コンパイル時に、SCSS内の行番号を出力するか否か
line_comments = (environment == :production) ? :false : :true
```

## "StyleDocco"

```bash:bash
$ npm install -fg styledocco
```

## "Grunt"のインストール

### "grunt-cli"のインストール

[Grunt](http://gruntjs.com/)をコマンドラインから利用するために、`grunt-cli`パッケージをインストールします。

```bash:bash
$ npm install grunt-cli -g
```

`-g` オプションは"グローバル"というオプションです。
グローバルオプションを指定する事により、作業ディレクトリー外のどんな場所でも`grunt`コマンドが使用可能になります。

### "Grunt"本体のインストール

Compassプロジェクトのディレクトリーに`Grunt`本体をインストールします。

```bash:bash
$ cd ~/develop/grunt/grunt-test

$ npm init
# 色々と聞かれますが、基本はデフォルトでOKです。
# entry point: (index.js) のみ Gruntfile.js を指定しました。
# このコマンドで、package.jsonが生成されます。

$ npm install grunt --save-dev
```

`--save-dev` オプションは　作業ディレクトリーに配置される `package.json`　に依存性を記述するためのオプションです。
複数人で開発を行う場合、`package.json` を共有する事により、同様の開発環境を簡単に構築する事が出来ます。

### "Gruntプラグイン"のインストール

既にGruntを便利に使うためのプラグインが複数用意されています。
プラグインは、[公式サイト](http://gruntjs.com/plugins)から探す事が可能です。


今回は、下記のプラグインを使用します。

+ [grunt-contrib-compass](https://www.npmjs.org/package/grunt-contrib-compass) - Compassのコンパイル
+ [grunt-styledocco](https://www.npmjs.org/package/grunt-styledocco) - StyleDoccoによるCSSスタイルガイド作成
+ [grunt-este-watch](https://www.npmjs.org/package/grunt-este-watch) - ファイルの監視

まとめてインストールします。

```bash:bash
$ npm install grunt-contrib-compass grunt-styledocco grunt-este-watch --save-dev
```

## "Gruntfile.js"の作成

`bundle exec`形式で実行される用に記述します。

+ `grunt-contrib-compass`には、`bundleExec`というオプションがあり、`true`を指定する事で`bundle exec`形式で実行してくれます。
+ `grunt-styledocco`の`options.preprocessor`には、頭に`bundle exec`を追記します。

```javascript:~/develop/grunt/grunt-test/Gruntfile.js
module.exports = function(grunt){
  grunt.initConfig({
    // grunt-contrib-compassの設定
    compass: {
      // 本番環境
      dist: {
        options: {
          config: 'config.rb',
          bundleExec: true,
          environment: 'production' // 環境の指定
        }
      }
    },

    // grunt-styledoccoの設定
    styledocco: {
      dist: {
        options: {
          name: 'grunt-test',
          preprocessor: 'bundle exec scss --compass'
        },
        files: {
          'docs/styleguide': 'scss'
        }
      }
    },

    // grunt-este-watchの設定
    esteWatch: {
      options: {
        dirs: ['scss'],
        livereload: false
      },
      scss: function(filepath){
        return ['compass', 'styledocco'];
      }
    }
  });

  grunt.loadNpmTasks('grunt-contrib-compass');
  grunt.loadNpmTasks('grunt-styledocco');
  grunt.loadNpmTasks('grunt-este-watch');
  
  grunt.registerTask('default', ['compass', 'styledocco']);
  grunt.registerTask('watch', ['esteWatch']);
};
```

## "Grunt"の実行

### 任意のタイミングでコンパイル・スタイルガイドの生成をする場合

`~/develop/grunt/grunt-test`にて、`grunt`コマンドを実行します。

```bash:bash
$ grunt
```

### 監視モードで、コンパイル・スタイルガイドの生成をする場合

`~/develop/grunt/grunt-test`にて、`grunt watch`コマンドを実行します。

```bash:bash
$ grunt watch
```