hubotに仕様書を作ってもらい、ブラウザで確認できるようする。

はじめに

hubotは公式サイトではcoffeescriptで書かれています。しかしながら最近ではES6で書く方も増えてきているようで、読み解く時に助かるのが仕様書ですよね。
なので仕様書をhubotの中で出力、ブラウザ経由で確認できるようにしてみました。

方法

1.jsdocの用意
2.ブラウザ表示の準備
3.jsdocで出力

hubotにはexpressがそ入っておりhttpリクエストなど受け付けることができます。
なのでそれを利用すれば簡単にブラウザに表示することができます。

ディレクトリ構成

hubot
├── Procfile
├── README.md
├── bin
│ ├── hubot
│ └── hubot.cmd
├── external-scripts.json
├──node_modules
│ └── ...
├── package.json
├── views
│　　　└── out
│　　　　　　└── index.html
│ └── .....
└── scripts
　　　　└── views.js

太字が今回の作業で追加されるものです。viewsフォルダは最初はないので作ってください。

jsdocの用意

まずはnpmから

npm install -g jsdoc

jsdocは以下のフォーマットを読み込んでくれます。

hoge.js

/**
 * メソッドの説明
 * @param {String} hoge  引数
 * 
 * @return {String}　hige 返り値
 */
function getTagName(source,msg,releaseBranchName){
}

jsdocの準備はこれでOKです。

ブラウザ表示の準備

expressは元々htmlやcssmのような静的ファイルは読み込みません。なのでそれらも読み込めるようにしてあげる必要があります。

views.js

//viewの中の静的ファイルを表示をするファイル

module.exports = (robot) => {
  var express = require('express');
  robot.router.use(express.static(__dirname + '/views'));
};

これで、viewsの中の静的ファイルが読み込まれるようになりました。

jsdocで出力

あとはjsdocを出力するだけです。グローバルのnpmに入れているのでviewsファイルの中で

jsdoc [出力したいファイルのパス]

するとoutというフォルダの中にhtmlが出力されていると思います。

あとはブラウザでhttp://[hubotがいるサーバーのIP]/out/index.htmlにアクセスして表示されたら成功です！

まとめ

仕様書はコードを理解する一助になるので、あると大変助かると思います。(特にjsだと)
ちなみに他のファイルを出力してもoutの中に排出されindex.htmlから飛ぶことができるようになりますので、じゃんじゃん仕様書作らせてあげてください！