Styledocco

@GeckoTang

Styledoccoとは

• CSS/Sass上のコメントをパースしてスタイルガイドを生成する
• Gruntのプラグインもある
• 他にも KSS, KSS-node, Kalei などがある。

Styledoccoを選んだ理由

• Compass使っても問題ない
• ある程度見た目良い
• Markdownで記述していく
• プレビューエリアのリサイズ機能240,320,768,1024,1280px

KSS-nodeはLessしか使えないの…

GruntからStyleDoccoする

必要そうなものをインストール...

npm install styledocco --save-dev
npm install grunt-styleguide --save-dev
npm install grunt-contrib-sass --save-dev
npm install grunt-contrib-clean --save-dev
npm install grunt-contrib-watch --save-dev

※grunt-styleguideはstyledoccoとKSS-nodeのラッパーです

ディレクトリ構成

files
┣doc
┗css
　┣src
　┃┣doc-preview.js
　┃┣README.md
　┃┣style.scss
　┃┗partial
　┃　┣_button.scss
　┃　┗_mixin.scss
　┣vendor
　┃┣_media-queries.scss
　┃┗_normalize.scss
　┗style.css

※doc-preview.jsはプレビューエリア用に追加したJSです

Gruntfile.jsを書きます。

module.exports = function(grunt){
  var matchdep = require('matchdep');
  matchdep.filterDev('grunt-*').forEach(grunt.loadNpmTasks);

  var config = {
    pkg: grunt.file.readJSON('package.json'),
    styleguide: {
      styledocco: {
        options: {
          framework: { name: 'styledocco' },
          name: 'プロジェクトX',
          template: { include: ['files/css/src/doc-preview.js'] }
        },
        src: [ 'files/css/**/*.scss', '!files/css/vendor/**/*.scss' ],
        dest: 'files/doc'
      }
    },
    sass: {
      dist: {
        options: { style: 'expanded' },
        files: { 'files/css/style.css': 'files/css/src/style.scss' }
      }
    },
    clean: ['<%= styleguide.styledocco.dest %>'],
    watch: {
      scss: {
        files: 'files/css/**/*.scss',
        tasks: ['clean', 'sass', 'styleguide']
      }
    }
  };
  grunt.initConfig(config);
  grunt.registerTask('default', ['watch']);
  grunt.registerTask('build', ['clean', 'sass', 'styleguide']);
};

SCSSを書きます。

.button{
    display: inline-block;
    font-size: 14px;
    color: #fff;
    background-color: #ccc;
    padding: 1em;
    border-radius: 10px;
    &:hover {
        color: $background;
        background-color: $color;
        box-shadow: 0 0 2px #000;
    }
    &:active {
        position: relative;
        top: 2px;
        color: $background;
        background-color: $color;
        box-shadow: inset 0 0 10px #000;
    }
    &.is-disabled {
        color: #fff;
        background-color: #ccc;
    }
}

スタイルガイド用にコメントを追記します。

コメントの書き方

コメントアウトの中にMarkdownで書く。 スペースを行頭に入れるとスタイルガイド上には反映されません

// #見出し1になる
// これは文章です。これは文章です。
 // これはドキュメントには反映されません

/*
 # 見出し1になる
 これは文章です。これは文章です。

    <div class="mod-box"></div>

*/

コードフェンスで囲うか、4スペースインデントしてHTMLを書くことで スタイルガイド上に、プレビューエリアが作成されます。

SCSSにコメントを追記

/*
## 普通のボタン

    <a class="button" href="#">normal</a>
    <a class="button  :hover" href="#">hover</a>
    <a class="button  :active" href="#">active</a>
    <a class="button  is-disabled" href="#">disabled</a>

*/
.button{
    display: inline-block;
    font-size: 14px;
    color: #fff;
    background-color: #ccc;
    padding: 1em;
    border-radius: 10px;
    &:hover {
        color: $background;
        background-color: tomato;
        box-shadow: 0 0 2px #000;
    }
    &:active {
        position: relative;
        top: 2px;
        color: $background;
        background-color: tomato;
        box-shadow: inset 0 0 10px #000;
    }
    &.is-disabled {
        color: #fff;
        background-color: #ccc;
    }
}

プレビューさせるHTMLのclass属性に:hoverや:activeなどの擬似クラスを書くと その状態のプレビューが可能になります。

そして生成

grunt build

docsの中にHTMLができているので確認する。

┣docs
┃┣index.html
┃┣style.html
┃┣partial-button.html
┃┗partial-mixin.html
┗css
　┣src
　┣vendor
　┗style.css

こんな感じ

StyleDoccoの不具合

• 擬似クラスのプレビューがSafariでしか動かない。なのでプレビューエリアにjs追加してごにょってしてる
• 一度生成したあとに再生成しても反映されない。docsディレクトリを空にしてから生成するとうまくいくので、grunt-contrib-cleanを使う

やらないほうがいい事

• watchしてscssを変更するたびにスタイルガイド生成若干時間かかる。デプロイ時など何かしらのタイミングでやるのがいい
• jsDocのような@mixinや@functionのドキュメントpre要素とか使えば出来なくはないけど、 StyleDoccoやKSSは、あくまでスタイルガイド

おまけ:プレビューの仕組み