grunt-styleguide, grunt-contrib-yuidocでsass(css), jsのドキュメントを自動作成する[grunt,sass]

今回の目的は、gruntでsass(css), jsのドキュメントを自動で生成する環境を用意することです。

grunt-styleguide, grunt-contrib-yuidocを利用します。

https://github.com/indieisaconcept/grunt-styleguide

https://github.com/gruntjs/grunt-contrib-yuidoc

http://yui.github.io/yuidoc/

install

$ npm i grunt-styleguide -D

$ npm i grunt-contrib-yuidoc -D

grunt/styleguide.js

frameworkはstyledoccoを利用したいと思います。

<%= yeoman.app %>/styles/*/.scssを対象として、docs/styledoccoにドキュメントを作成します。

'use strict';

module.exports = function(grunt) {

    grunt.config('styleguide', {
        all: {
            files: {
                'docs/styledocco': '<%= yeoman.app %>/styles/**/*.scss',
            }
        }
    });
};

grunt/contrib-yuidoc.js

<%= yeoman.app %>/scripts/を対象として、docs/yuidocにドキュメントを作成します。

'use strict';

module.exports = function(grunt) {

    grunt.config('yuidoc', {
        compile: {
            options: {
                paths: '<%= yeoman.app %>/scripts',
                outdir: 'docs/yuidoc'
            }
        }
    });
};

grunt/contlib-clean.js

clean:docsタスクとして、docs/の削除を追加します。

'use strict';

module.exports = function(grunt) {

    grunt.config('clean', {
        dist: {
            files: [{
                dot: true,
                src: [
                    '.tmp',
                    '<%= yeoman.dist %>/*',
                    '!<%= yeoman.dist %>/.git*'
                ]
            }]
        },
        server: '.tmp',
        docs: 'docs'
    });

};

port.json

docs/への参照用のポート番号（今回は40000）を設定します。

{
  "connect": {
    "livereload": 10000,
    "dist": 20000
  },
  "livereload": 30000,
  "docs": 40000,
  "stubby": {
    "stubs": 8000,
    "tls": 8443,
    "admin": 8010
  }
}

Gruntfile.js

connect.docsタスクとして、docs/のファイルを参照できるようにします。

ポート番号はport.jsonで定義した値を設定します。

docsタスクとして、各種タスクを設定します。

・
・
・
var port = require('./port.json');
・
・
・
        connect: {
            options: {
                // change this to '0.0.0.0' to access the server from outside
                hostname: '0.0.0.0'
            },
            livereload: {
                options: {
                    port: port.connect.livereload,
                    middleware: function (connect) {
                        return [
                            lrSnippet,
                            mountFolder(connect, '.tmp'),
                            mountFolder(connect, yeomanConfig.app),
                            require('grunt-connect-proxy/lib/utils').proxyRequest
                        ];
                    }
                }
            },
            test: {
                options: {
                    middleware: function (connect) {
                        return [
                            mountFolder(connect, '.tmp'),
                            mountFolder(connect, 'test')
                        ];
                    }
                }
            },
            dist: {
                options: {
                    port: port.connect.dist,
                    middleware: function (connect) {
                        return [
                            mountFolder(connect, yeomanConfig.dist),
                            require('grunt-connect-proxy/lib/utils').proxyRequest
                        ];
                    }
                }
            },
            docs: {
                options: {
                    port: port.docs,
                    middleware: function (connect) {
                        return [
                            mountFolder(connect, 'docs')
                        ];
                    }
                }
            },
            proxies: [
                {
                    context: '/ajax',
                    host: '0.0.0.0',
                    port: port.stubby.stubs,
                    https: false,
                    changeOrigin: false,
                    xforward: false
                }
            ]
        },
・
・
・
    grunt.registerTask('docs', [
        'clean:docs',
        'styleguide',
        'yuidoc',
    'connect:docs:keepalive'
    ]);
・
・
・

サンプルファイルを用意する

app/styles/hoge.scss

/* Provides extra visual weight and identifies the primary action in a set of buttons.

    <button class="btn primary">Primary</button>
*/
.btn.primary {
    background: steelblue;
    color: snow;
    border: 2px outset steelblue;
}

app/scripts/hoge.js

/**
* This is the description for my class.
*
* @class MyClass
* @constructor
*/

/**
* My method description.  Like other pieces of your comment blocks, 
* this can span multiple lines.
*
* @method methodName
* @param {String} foo Argument 1
* @param {Object} config A config object
* @param {String} config.name The name on the config object
* @param {Function} config.callback A callback function on the config object
* @param {Boolean} [extra=false] Do extra, optional work
* @return {Boolean} Returns true on success
*/

/**
* My property description.  Like other pieces of your comment blocks, 
* this can span multiple lines.
* 
* @property propertyName
* @type {Object}
* @default "foo"
*/

動作確認

$ grunt docs

Running "clean:docs" (clean) task
Cleaning "docs"...OK

Running "styleguide:all" (styleguide) task

>> DEST: docs/styledocco/index.html

Running "yuidoc:compile" (yuidoc) task
Start YUIDoc compile...
Scanning: app/scripts
Output: docs/yuidoc
YUIDoc compile completed in 0.312 seconds

Running "connect:docs:keepalive" (connect) task
Starting connect web server on 0.0.0.0:40000.
Waiting forever...

各URLにアクセスし、画面が表示されれば成功です。

http://XXXX:40000/styledocco/
http://XXXX:40000/yuidoc/