たった3ステップでできる！ gulpでJSDocコメントからHTMLを自動書き出しする方法

メンテナンス済み / 株式会社ICS
15

先日、弊社池田が記事「JavaScriptでJSDocコメントを書くメリットとは」でJSDocコメントの有用性についてご紹介しました。その中で「APIリファレンスの書き出し」をメリットの1つとして取り上げていますが、今回はそこをタスクランナーであるgulpを使ってリファレンスのHTMLファイルを自動書き出しする方法をご紹介します。

※すでにgulpの環境が構築されている状態を想定してご紹介します。gulpについての詳細は記事「5分で導入できる！ タスクランナーGulpを使ってウェブ制作を爆速にしよう」をご覧ください。

なぜgulpを使うのか

JSDocの書き出し自体はNode.jsとyuidocjs等で行えるのですが、gulpを使うことで他のタスク（JavaScriptをminifyする等）と一緒に自動化できるというメリットを得られるためです。

JSDocを書き出したいプロジェクトのサンプルを下記に用意しました。書き出すHTMLのindex.htmlに流しこむことができるREADME.mdをプロジェクトのルートへ、JSDocコメントが書かれたJavaScriptを「src」フォルダーへ格納してあります。書き出されたHTMLを格納するため「docs」フォルダー格納されます。

Step1 gulpプラグインをインストールしよう

まずはJSDocコメントをHTMLに書き出してくれるプラグインであるgulp-jsdocをインストールします。コマンドラインツール（Macならターミナル、Windowsならコマンドプロンプト等）で先ほど用意したフォルダーのルートへ移動し下記のコマンドを実行します。

npm install gulp-jsdoc

Step2 パラメーター・タスクの設定

HTMLをどのように書き出したいのかgulp-jsdocのパラメーターを設定します。とくに設定しなくても書き出すことはできるのですが、設定することでHTML内にプロジェクトのバージョンなどを記述したり、HTMLのスタイルを指定できるようになります。下記はgulpのタスクを記述したgulpfile.jsです。HTMLのテンプレートとしてink-docstrapを使用しています。他にも細かくパラメーターを設定できるので興味のある方はご覧ください。こちらはgulp-jsdocをインストールすると同封されるので別途インストールの必要はありません。

// gulp
var gulp = require("gulp");

// gulp-jsdoc
var jsdoc = require("gulp-jsdoc");

// プロジェクト情報
var infos = {
  // プロジェクト名
  name: "SampleJS",

  // バージョン
  version: "1.0.0"
};

// HTMLのテンプレート設定
var template = {
  // テンプレートプラグイン「ink-docstrap」を使用する
  path: "ink-docstrap",

  // プロジェクト名 ページタイトル・ヘッダーの左上に表示されます
  systemName: "SampleJS",

  // HTMLのスタイルテーマ
  // cerulean, cosmo, cyborg, darkly, flatly, journal, lumen, paper, readable, sandstone, simplex, slate, spacelab, superhero, united, yetiの中から選べます
  theme: "cosmo",

  // ソースコードに行番号を表示するかどうか
  linenums: true
};

// オプション
var options = {
  // ソースコードを記述したHTMLを生成するかどうか
  outputSourceFiles: true
};

// jsdocを書き出すタスク
gulp.task("jsdoc", function() {
  // 書き出されるindex.htmlに「README.md」を埋め込む
  gulp
    .src(["./src/**/*.js", "README.md"])
    .pipe(jsdoc.parser(infos))
    .pipe(jsdoc.generator("./docs/", template, options));
});

// watch
gulp.task("watch", function() {
  gulp.watch("./src/**/*.js", ["jsdoc"]);
});

// 起動時に一度jsdocタスクを実行しwatchを開始
gulp.task("default", ["watch", "jsdoc"]);

Step3 書き出し！

いよいよ書き出しです。心の準備はよろしいでしょうか？　下記コマンドを実行してください。

gulp

「docs」フォルダーにHTMLがずらっと格納されると成功です。先ほどgulpfile.jsで指定したプロジェクト名・バージョンでフォルダーが作成されました。

書き出されたindex.htmlをWebブラウザで開くとこのように表示されます。左カラムにREADME.mdの内容が埋め込まれ、右カラムにローカルナビゲーションが設置されています。

各クラスのページを開くとパラメーターの説明部分などにテンプレートのスタイルが適応され読みやすくなっています。

ソースコードもカラーリングされています。

最後に

JSDocのHTML書き出しを自動化することでJavaScriptのソースコードとドキュメントに差異もでることなく安心して開発を進められます。今回かかった手間と得られるメリットを比べても断然メリットのほうが大きいかと思います。今後のプロジェクトへの導入を検討されてはいかがでしょうか？

トップページに戻る