いまさらだけど Hubot のドキュメントを読んでみよう

これは [Hubot Advent Calendar 2014][hubot-adventar-2014] の 21 日目の記事です。

また、今回は @bouzuya の Hubot 連載の第 13 回です。[目次は、第 1 回の記事にある][hubot-adventar-2014-bouzuya-index]ので、そちらをどうぞ。

ちなみに Hubot Advent Calendar 2014 の 20 日目は [Hubotと二人暮らし（構想編）][hubot-adventar-2014-20] でした。ロボットに指示して家電操作とかって憧れますね。ぼくもやってますよ。Hubot と IRKit 使って。Arduino もためしてますが、Lチカレベルで止まってますね。 ngs さんレベルになると水やりくらい余裕みたいですけど。

# 前回まで、そして今回は

さて、前回は [robot.brain を永続化する Hubot スクリプトをつくろう][hubot-adventar-2014-19] ということで、`robot.brain` を永続化する Hubot スクリプトをつくりました。

今回は、プログラミングからはちょっと離れて Hubot のドキュメントについて紹介します。

いまさらではありますが、ぼくは「ぼくの連載を読むくらいならドキュメントとソースコードとを読むほうが良い」と考えています。いままで「ソースコードを読め」というのはしつこく書いた気がするのですが、「ドキュメント」についてはあまり触れてこなかったので、今回はそこにフォーカスしてみます。

# Hubot のドキュメント

では Hubot のドキュメントってどこにあるんでしょう。

答えは GitHub にある [github/hubot][] リポジトリの `docs/` です。

逆に言うと、ほかにまともなドキュメントはありません。ドキュメントを含んだ [github/hubot][] だけを見ておけば、Hubot を知っている顔をしてツイートして良いのです。

さっそく紹介していきましょう。リンクは最後の「まとめ」にまとめていますので、簡単に各ドキュメントを説明していきます。

まずは `docs/README.md` ですね。リポジトリルートの `README.md` から参照されています。Hubot の導入と各ドキュメントへのリンクが書かれています。

つぎは `docs/scripting.md` です。スクリプトの書きかたが書かれています。読み込みから `robot.hear` / `robot.respond` / `msg.send` / `msg.reply` / `robot.http` / `msg.random` / `process.env` / `setTimeout` / `setInterval` / `robot.router` / `robot.brain.get` / `robot.brain.set` など、この連載で触れてきたトピックがたったの 1 ファイルにまとまっています。触れられていないものもあります。

つぎは `docs/adapters.md` です。アダプターの紹介が書かれています。アダプターについてのドキュメントはなく「ソースコード読め」と書いてあります。この連載では最後に扱う予定です (あと 4 日のどこかで) 。

つぎは `docs/deploying/heroku.md` / `docs/deploying/unix.md` / `docs/deploying/windows.md` です。Heroku / UNIX / Windows の各環境へのデプロイ方法が書かれています。

最後は `docs/patterns.md` です。「パターン！？」と期待するかもしれませんが、ここにはほとんど情報はありません。Hubot の名前が変わった場合に別名へ誘導する方法と、コマンドが変わった場合に別コマンドへ誘導する方法とが書かれているだけです。

すこしズレるので割愛しますが、Hubot に同梱の Shell / Campfire アダプターの `README.md` も含んでいます。個人的には別リポジトリにすればいいのにって思いますけど。

# まとめ

まとめると次のとおりです。

- `dos/README.md`: https://github.com/github/hubot/tree/v2.10.0/docs/README.md
- `docs/scripting.md`: https://github.com/github/hubot/blob/v2.10.0/docs/scripting.md
- `docs/adapters.md`: https://github.com/github/hubot/blob/v2.10.0/docs/adapters.md
- `docs/deploying/heroku.md`: https://github.com/github/hubot/blob/v2.10.0/docs/deploying/heroku.md
- `docs/deploying/unix.md`: https://github.com/github/hubot/blob/v2.10.0/docs/deploying/unix.md
- `docs/deploying/windows.md`: https://github.com/github/hubot/blob/v2.10.0/docs/deploying/windows.md

私見ですが、`docs/README.md` と `docs/scripting.md` 以外はほとんど役に立たない気がします。量はないので、ひととおり目を通すと良いと思います。

# 最後に

準備を忘れていたので、ドキュメント紹介でお茶を濁してみました。

ただ、最初に書いた「ぼくの連載を読むくらいならドキュメントとソースコードとを読むほうが良い」は正しいと思います。連載をひととおり読むより `docs/scripting.md` を読むほうが早いです。

ドキュメントをひととおり読んだら、ソースコードもぜひ読んでほしいです。
  
  
[getting-started-with-hubot]: https://github.com/github/hubot/tree/v2.9.3/docs#getting-started-with-hubot
[bouzuya/hubot-hello-world]: https://github.com/bouzuya/hubot-hello-world/
[bouzuya/hubot-choice]: https://github.com/bouzuya/hubot-choice/
[bouzuya/hubot-adventar]: https://github.com/bouzuya/hubot-adventar/
[bouzuya/hubot-homepage]: https://github.com/bouzuya/hubot-homepage/
[bouzuya/hubot-script-gist]: https://github.com/bouzuya/hubot-script-gist/
[bouzuya/hubot-brainfxxk]: https://github.com/bouzuya/hubot-brainfxxk/
[bouzuya/hubot-7days-later]: https://github.com/bouzuya/hubot-7days-later/
[bouzuya/hubot-file-brain]: https://github.com/bouzuya/hubot-file-brain/
[hubot-scripts/hubot-redis-brain]: https://github.com/hubot-scripts/hubot-redis-brain
[hubot-script-per-day-61]: http://bouzuya.hatenablog.com/entry/2014/09/12/224215
[github/hubot]: https://github.com/github/hubot/
[github/generator-hubot]: https://github.com/github/generator-hubot/
[ops-for-everyone]: https://speakerdeck.com/johndbritton/ops-for-everyone
[adventar]: http://www.adventar.org/
[express-reference]: http://expressjs.com/3x/api.html
[hubot.github.com]: https://hubot.github.com/
[hubot-adventar-2014]: http://www.adventar.org/calendars/384
[hubot-adventar-2014-bouzuya-index]: http://qiita.com/bouzuya/items/c7d0ad80c357aab6b696
[hubot-adventar-2014-1]: http://qiita.com/bouzuya/items/c7d0ad80c357aab6b696
[hubot-adventar-2014-2]: http://qiita.com/bouzuya/items/11c0c6da2b3ad54b827f
[hubot-adventar-2014-3]: http://qiita.com/bouzuya/items/2a200c9e8a45e2478bc2
[hubot-adventar-2014-4]: http://qiita.com/bouzuya/items/4c0206d72ff22ade9339
[hubot-adventar-2014-5]: http://pasero.net/~mako/blog/s/685
[hubot-adventar-2014-6]: http://qiita.com/bouzuya/items/4e051f68f8d68a2944b0
[hubot-adventar-2014-7]: http://qiita.com/bouzuya/items/2e935c99647b93d8ee1d
[hubot-adventar-2014-8]: http://udzura.hatenablog.jp/entry/2014/12/08/182744
[hubot-adventar-2014-9]: http://qiita.com/bouzuya/items/587c4e920151342e6f1d
[hubot-adventar-2014-10]: http://qiita.com/bouzuya/items/8e8ee8e2e8f83513ad35
[hubot-adventar-2014-11]: http://qiita.com/bouzuya/items/3e239bc530e7c2c3a26c
[hubot-adventar-2014-12]: http://qiita.com/hiconyan/items/3e5481a61657890624dc
[hubot-adventar-2014-13]: http://pasero.net/~mako/blog/s/689
[hubot-adventar-2014-16]: http://qiita.com/bouzuya/items/d65a394cac9e76b56d3d
[hubot-adventar-2014-17]: http://qiita.com/hiconyan/items/baf6ac56129a26d8ac0c
[hubot-adventar-2014-18]: http://qiita.com/bouzuya/items/d5fd0ef9a8cb100933f4
[hubot-adventar-2014-19]: http://qiita.com/bouzuya/items/ae1cb5610a64794bc522
[hubot-adventar-2014-20]: http://bochibochibocchi0095.hatenablog.com/entry/2014/12/21/000710