ngdoc - Yeoman Advent Calendar 2015

ngdoc を紹介する。ngdocと言ってもYEOMANジェネレータの。AngularのngDocの書き方に従えば自プロジェクトを良いようにドキュメント化してくれる。このエントリーは「Yeoman Advent Calendar 2015」12月4日の記事です。

www.npmjs.com

ngDoc

ngDocの書き方はサンプルとしてこれ。

/**
 *
 * @ngdoc directive
 * @name awesomeElement
 * @module myModule
 * @restrict E
 * @descrition
 * This is an awesome directive!
 *
**/
angular.module('myModule')
  .directive('awesomeElement', function () {
    return {
      // Derective definision... 
    };
  });

インストール

$ npm install -g generator-ngdoc
$ mkdir mydir && cd $_
$ yo ngdoc

実行

$ cd docs
$ gulp docs:serve

ブラウザが立ち上がりアプリが表示される

自分のプロジェクトにこれを入れたい場合、自プロジェクトディレクトリに行ってその中で

$ yo ngdoc
$ cd docs
$ gulp docs:serve

ただデフォだとsrcディレクトリを見ているのでdocs/gulp/dgeni.jsを編集する、９行目の部分。

 1    // Prease see also 'docs/config/index.js'.
 2    var dgeni = new Dgeni([require('../config/')
 3      .config(function (readFilesProcessor, writeFilesProcessor) {
 4
 5        // Specify the base path used when resolving relative paths to source and output files
 6        readFilesProcessor.basePath = path.resolve(__dirname, '../..');
 7
 8        // Specify collections of source files that should contain the documentation to extract
 9        readFilesProcessor.sourceFiles = [{include: 'src/**/*.js', basePath: 'src'}, {include: 'docs/content/**/*.ngdoc',basePath: 'docs/content'}];
10
11        //templateFinder.templateFolders.unshift(path.resolve(__dirname, 'templates'));
12        writeFilesProcessor.outputFolder  = 'docs/.tmp';
13      })

最後に

ちょっと変わった使い方。こういうジェネレータもあるんだね