StyleDoccoでstyleguideを作成

node

フロントエンドの開発で業務を引き継ぐと面倒なのがスタイルシートの仕様の把握です。
スタイルガイドがあるとメンテナンスやアップデートも非常に行いやすいのですが、スタイルガイドを作成するのは結構面倒。

そんなこんなでcssのコメントで対応してたが、そろそろキチンとしよう思い、styleguide document generatorを検討してみた。

styleguide document generatorについて

有名どころの StyleDocco と kss があるので、今回はStyleDoccoについて。

StyleDocco generates style guide documents from your stylesheets by parsing your stylesheet comments through Markdown.

You can write HTML snippets in your stylesheet comments, prefixed with 4 spaces or between code fences (｀｀｀), and StyleDocco will show a preview with the styles applied, as well as display the example HTML code. The previews are rendered in a resizable iframes to make it easy to demonstrate responsive designs at different viewport sizes.

ざっくりと
StyleDoccoはstylesheetsにmarkdown形式でコメントを記述すると、styleguide documentを生成するジェネレーター。
markdown形式でhtmlのスニペットを記述すると、インラインフレーム内にプレビュー用のhtmlが出力されます。

また、cssのほかSASS, SCSS, Less, Stylusというプリプロセッサーにも対応してます。

既存の環境にも簡単に導入でき、自由度が高いので、よさそう。

環境セットアップ

まずは環境セットアップから。

StyleDoccoはnodejsが必要なのでまずはnode.jsのインストール。

nodejsは開発サイクルが早いのでとりあえずバージョン管理ツールで複数バージョンを管理する。
nodejsのバージョン管理はnodebrewが良さそうなので

1
2
3
4
5
6
# install
$curl https://raw.github.com/hokaccha/nodebrew/master/nodebrew | perl - setup

# パスを通す
$export PATH=$HOME/.nodebrew/current/bin:$PATH
$source ~/.bashrc

nodebrewの使い方は割愛。
今回はnodejsの安定バージョンを使うので

1
2
3
4
5
6
7
8
9
10
11
12
13
14
// インストール
$nodebrew install stable

// リストを確認
$nodebrew ls
v0.8.15

// alias作成
$nodebrew alias default v0.8.15
default -> v0.8.15

// 使用するaliasを設定
$nodebrew use default
use v0.8.15

続いてStyleDoccoをinstall

1
$npm install styledocco　ーg

スタイルガイドを生成する

適当に以下の様なディレクトリ構造を作成して、

1
2
3
styledocco
└── sass
　　　└── buttons.scss

sassファイルにmarkdown形式でコメントを追加。
mixinやextendももちろん使用できます。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
/*
## Gradient

.gladient  - mixin gradient

***

- $start - The color hex at the top.
- $end   - The color hex at the bottom.

 */
@mixin gradient($start, $end){
  background: $start;
  background: -webkit-gradient(linear, left top, left bottom, from($start), to($end));
  background: -moz-linear-gradient(top, $start, $end);
  background: -o-linear-gradient($start, $end);
  background: linear-gradient($start, $end);
  filter: progid:DXImageTransform.Microsoft.gradient(startColorstr='#{$start}', endColorstr='#{$end}');
  zoom:1;
}

/*
# Button.
## Standard Buttons

:hover    - Hovering highlights.
:disabled - Disabled Style.

***
｀｀｀
    <button>Standard Button</button>
｀｀｀

***

｀｀｀
    <button disabled="disabled">Disabled Button</button>
｀｀｀

*/
button {
  @include gradient(#fefefe, #e6e6e6);
  padding: 5px 15px;
  border: 1px solid #d0d0d0;
  border-radius: 3px;
  box-shadow: 0 1px 4px rgba(0, 0, 0, 0.15);
  color: #666;
  text-shadow: 0 1px rgba(255, 255, 255, 0.9);
  font-weight: bold;
  font-size: 12px;
  font-family: "Helvetica Neue", Helvetica;
  line-height: normal;
  cursor: pointer;
  &:hover {
    @include gradient(#f6f6f6, #E6E6E6);
    border-color: #C5C5C5;
    color: #666;
  }
  &:disabled {
    opacity: 0.5;
  }
}

/*
## Primary Buttons

.primary  - Primary action button style.
***

｀｀｀
    <button class="primary">Primary Button</button>
｀｀｀

 */

.primary, 
.primary:hover {
  @include gradient(#007fcc, #0045cc);
  @extend button;
  border-color: #0062b8;
  box-shadow: 0 1px 4px rgba(0, 0, 0, 0.2);
  color: #fff;
  text-shadow: 0 -1px 0 rgba(0, 0, 0, 0.4);
}

/*
## Small Buttons

.smaller  - Smaller size button

***

｀｀｀
    <button class="smaller">Small Button</button>
｀｀｀
 */

.smaller {
  @extend button;
  padding: 4px 7px;
  font-size: 11px; 
}

さっそく styleguide documentを作成してみます。

1
2
3
4
5
6
7
// options
// -n プロジェクト名
// -o アウトプットディレクトリ(default: docs)
// --preprocessor プリプロセッサー
// --include プレビューに含むファイルを指定
// --verbose document生成時に出力するメッセージ (default: false)
$styledocco -n "styledocco" --preprocessor "sass" sass/buttons.scss

とすることで、

1
2
3
4
5
6
styledocco
├── sass
│　　└── buttons.scss
└── docs
     ├ index.html
     └ buttons.html

とdocsディレクトリにstyleguide documentが出力されます。
こんな感じでページが生成されます。

styledoccoのページのイメージ

コードスニペットに要素のスタイル、デバイスの大きさを切り替えて確認もできるという至れり尽くせりでした。

Gruntで使う

ということで、これを自分のGruntのビルド環境に組み込む。
gruntでshellからstyledoccoを実行してもいいのですが、 grunt-styleguide というものが StyleDocco に対応していたのでそれを使ってみる。

自分のgrunt環境にgrunt-styleguideをインストール。

1
npm install grunt-styleguide --save-dev

タスクを追加

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
// styleguide
styleguide: {
       options: {
              framework: {
                name: 'styledocco'
              },
       },
       my_project: {
            styledocco: {
                options: {
                  framework: {
                    name: 'styledocco'
                  },
                  name: 'Style Guide',
                },
                files: {
                    'docs': 'sass/**/*.scss'           
                },
            }
},

// watch
watch: {
    styleguide: {
        files: [
            'sass/**/*.scss'
         ],
         tasks: 'styleguide'
    }
}
grunt.loadNpmTasks('grunt-styleguide');

という感じでwatchオプションに追加して、監視しておけば自動化できて便利。

StyleDoccoはコメントにmarkdown形式でスニペットをかけて簡単にstyleguide documentを生成できるのが便利。
grunt環境なら自動かもできる。rubyならrakeタスクに追加しとけばいいのかな。
導入しやすく、既存のプロジェクトのstyleguideを作成も容易です。

Comments