jsduckでjavascriptドキュメントを作ってみるメモ

はじめに

jsduckを使ってみたメモです

jsduckの導入に関してはこちらのサイトを参考にさせて頂きました
→JavaScript のコードからモダンなドキュメントをさくっと生成してくれる『JSDuck』の使い方 – 導入編

jsduck入れる

rubyとgem入れる

rubyとgem入ってなかったので入れてから試しましたが、そこに関しては本分ではないのでこちら↓に切り出しました

任意のディレクトリにrubyとgemをインストールを。

※今回のjsduckを使った環境はこっち↑で入れたrubyとgemにより動いてます

jsduck入れる

# /home/hoge/local/bin/gem install jsduck
Fetching: rdiscount-2.1.6.gem (100%)
Building native extensions.  This could take a while...
Fetching: json-1.8.0.gem (100%)
Building native extensions.  This could take a while...
Fetching: parallel-0.7.1.gem (100%)
Fetching: rkelly-remix-0.0.4.gem (100%)
Fetching: dimensions-1.2.0.gem (100%)
Fetching: jsduck-5.1.0.gem (100%)
Successfully installed rdiscount-2.1.6
Successfully installed json-1.8.0
Successfully installed parallel-0.7.1
Successfully installed rkelly-remix-0.0.4
Successfully installed dimensions-1.2.0
Successfully installed jsduck-5.1.0
6 gems installed
Installing ri documentation for rdiscount-2.1.6...
unable to convert "\xD0" from ASCII-8BIT to UTF-8 for lib/home/hoge/local/lib/ruby/site_ruby/2.0.0/x86_64-linux/rdiscount.so, skipping
Installing ri documentation for json-1.8.0...
unable to convert "\xA0" from ASCII-8BIT to UTF-8 for lib/home/hoge/local/lib/ruby/site_ruby/2.0.0/x86_64-linux/json/ext/generator.so, skipping
unable to convert "\xB0" from ASCII-8BIT to UTF-8 for lib/home/hoge/local/lib/ruby/site_ruby/2.0.0/x86_64-linux/json/ext/parser.so, skipping
Installing ri documentation for parallel-0.7.1...
Installing ri documentation for rkelly-remix-0.0.4...
Installing ri documentation for dimensions-1.2.0...
Installing ri documentation for jsduck-5.1.0...
unable to convert "\x89" from ASCII-8BIT to UTF-8 for lib/jsduck/tag/icons/cfg.png, skipping
unable to convert "\x89" from ASCII-8BIT to UTF-8 for lib/jsduck/tag/icons/css_mixin.png, skipping
unable to convert "\x89" from ASCII-8BIT to UTF-8 for lib/jsduck/tag/icons/css_var.png, skipping
unable to convert "\x89" from ASCII-8BIT to UTF-8 for lib/jsduck/tag/icons/event.png, skipping
unable to convert "\x89" from ASCII-8BIT to UTF-8 for lib/jsduck/tag/icons/method.png, skipping
unable to convert "\x89" from ASCII-8BIT to UTF-8 for lib/jsduck/tag/icons/property.png, skipping
Installing RDoc documentation for rdiscount-2.1.6...
unable to convert "\xD0" from ASCII-8BIT to UTF-8 for lib/home/hoge/local/lib/ruby/site_ruby/2.0.0/x86_64-linux/rdiscount.so, skipping
Installing RDoc documentation for json-1.8.0...
unable to convert "\xA0" from ASCII-8BIT to UTF-8 for lib/home/hoge/local/lib/ruby/site_ruby/2.0.0/x86_64-linux/json/ext/generator.so, skipping
unable to convert "\xB0" from ASCII-8BIT to UTF-8 for lib/home/hoge/local/lib/ruby/site_ruby/2.0.0/x86_64-linux/json/ext/parser.so, skipping
Installing RDoc documentation for parallel-0.7.1...
Installing RDoc documentation for rkelly-remix-0.0.4...
Installing RDoc documentation for dimensions-1.2.0...
Installing RDoc documentation for jsduck-5.1.0...
unable to convert "\x89" from ASCII-8BIT to UTF-8 for lib/jsduck/tag/icons/cfg.png, skipping
unable to convert "\x89" from ASCII-8BIT to UTF-8 for lib/jsduck/tag/icons/css_mixin.png, skipping
unable to convert "\x89" from ASCII-8BIT to UTF-8 for lib/jsduck/tag/icons/css_var.png, skipping
unable to convert "\x89" from ASCII-8BIT to UTF-8 for lib/jsduck/tag/icons/event.png, skipping
unable to convert "\x89" from ASCII-8BIT to UTF-8 for lib/jsduck/tag/icons/method.png, skipping
unable to convert "\x89" from ASCII-8BIT to UTF-8 for lib/jsduck/tag/icons/property.png, skipping

unable to convert "\xD0" from ASCII-8BIT to UTF-8 for lib/home/hoge/local/lib/ruby/site_ruby/2.0.0/x86_64-linux/rdiscount.so, skipping
とか怪しいの出ましたがとりあえず試すだけなので気にせず次へ。。。

確認

# /home/hoge/local/bin/jsduck --version
/home/hoge/local/lib/ruby/site_ruby/2.0.0/rubygems/custom_require.rb:36:in `require': cannot load such file -- rdiscount.so (LoadError)
        from /home/hoge/local/lib/ruby/site_ruby/2.0.0/rubygems/custom_require.rb:36:in `require'
        from /home/hoge/local/lib/ruby/gems/2.0.0/gems/rdiscount-2.1.6/lib/rdiscount.rb:106:in `<top (required)>'
        from /home/hoge/local/lib/ruby/site_ruby/2.0.0/rubygems/custom_require.rb:36:in `require'
        from /home/hoge/local/lib/ruby/site_ruby/2.0.0/rubygems/custom_require.rb:36:in `require'
        from /home/hoge/local/lib/ruby/gems/2.0.0/gems/jsduck-5.1.0/lib/jsduck/format/doc.rb:2:in `<top (required)>'
        from /home/hoge/local/lib/ruby/site_ruby/2.0.0/rubygems/custom_require.rb:36:in `require'
        from /home/hoge/local/lib/ruby/site_ruby/2.0.0/rubygems/custom_require.rb:36:in `require'
        from /home/hoge/local/lib/ruby/gems/2.0.0/gems/jsduck-5.1.0/lib/jsduck/assets.rb:8:in `<top (required)>'
        from /home/hoge/local/lib/ruby/site_ruby/2.0.0/rubygems/custom_require.rb:36:in `require'
        from /home/hoge/local/lib/ruby/site_ruby/2.0.0/rubygems/custom_require.rb:36:in `require'
        from /home/hoge/local/lib/ruby/gems/2.0.0/gems/jsduck-5.1.0/lib/jsduck/app.rb:3:in `<top (required)>'
        from /home/hoge/local/lib/ruby/site_ruby/2.0.0/rubygems/custom_require.rb:36:in `require'
        from /home/hoge/local/lib/ruby/site_ruby/2.0.0/rubygems/custom_require.rb:36:in `require'
        from /home/hoge/local/lib/ruby/gems/2.0.0/gems/jsduck-5.1.0/bin/jsduck:20:in `<top (required)>'
        from /home/hoge/local/bin/jsduck:19:in `load'
        from /home/hoge/local/bin/jsduck:19:in `<main>'

rdiscount.so見つからないと怒られる。。。汗

パスの問題っぽいけどとりあえずrdiscount.soとやらが本当にないのか確認

# locate rdiscount.so
ない。。。けど、たぶんlocateDBを更新してないからなので再度チャレンジ

# sudo updatedb
# locate rdiscount.so
/home/hoge/local/lib/ruby/gems/2.0.0/gems/rdiscount-2.1.6/ext/rdiscount.so
/home/hoge/local/lib/ruby/gems/2.0.0/gems/rdiscount-2.1.6/lib/home/hoge/local/lib/ruby/site_ruby/2.0.0/x86_64-linux/rdiscount.so

ブツはありそうなので、とりあえずエラーを起こしてるファイルを確認

# vi /home/hoge/local/lib/ruby/site_ruby/2.0.0/rubygems/custom_require.rb
→見た結果あまり関係なさそう

# vi /home/hoge/local/lib/ruby/gems/2.0.0/gems/rdiscount-2.1.6/lib/rdiscount.rb
→見た結果一番下に
require 'rdiscount.so'
の文字が。

さきほどlocateで確認したフルパスを入れて保存してみる
require 'rdiscount.so'
↓
require '/home/hoge/local/lib/ruby/gems/2.0.0/gems/rdiscount-2.1.6/ext/rdiscount.so'

再度確認

# /home/hoge/local/bin/jsduck --version
JSDuck 5.1.0

取りあえず動かすテストとしてはこれでOK。
フルパス入れて動くってことはやっぱパスの問題そーですね。

動かすテスト

参考サイトより、下記のコマンドでサンプル？のドキュメントができるようです

# pwd
/home/hoge/ruby
# /home/hoge/local/bin/jsduck --builtin-classes --output ./docs
# ll
drwxr-xr-x  7 hoge cam     4096  8月 25 20:07 2013 docs
drwxr-xr-x 25 hoge cam    12288  8月 25 18:08 2013 ruby-2.0.0-p247
-rw-r--r--  1 hoge cam 13652782  8月 25 18:02 2013 ruby-2.0.0-p247.tar.gz
drwxr-xr-x  7 hoge cam     4096  1月  7 04:34 2012 rubygems-1.8.15
-rw-r--r--  1 hoge cam   251305  1月  7 04:38 2012 rubygems-1.8.15.tgz
drwxr-xr-x  7 hoge cam     4096  1月 25 14:21 2013 rubygems-1.8.25
-rw-r--r--  1 hoge cam   380540  1月 26 00:55 2013 rubygems-1.8.25.tgz

普通に動いたので、作られた./docs/index.htmlをブラウザで見てみる

おお、jsのビルトインオブジェクトのドキュメントができてるぽい

適当なプロジェクトフォルダでドキュメントを作ってみる

※こちらも参考にさせて頂きました

# cd 適当なプロジェクトのpublickフォルダ
# ll
drwxr-xr-x 3 hoge hoge 4096  7月 22 20:21 2013 css
-rw-r--r-- 1 hoge hoge  321  5月  2 13:20 2013 index.html
drwxr-xr-x 4 hoge hoge 4096  8月 25 20:20 2013 js

ここでテスト
# jsduck ./js --output ./docs --title "test desuyo"
# ll
drwxr-xr-x 3 hoge hoge 4096  7月 22 20:21 2013 css
drwxr-xr-x 7 hoge hoge 4096  8月 25 20:24 2013 docs
-rw-r--r-- 1 hoge hoge  321  5月  2 13:20 2013 index.html
drwxr-xr-x 4 hoge hoge 4096  8月 25 20:20 2013 js

さきほどと同じようにdocディレクトリが作られたので
中にあるindex.htmlをブラウザで見てみる

なにもでない。。。

javadoc的に特定のコメントを書かいてないので、そうかなーとは思ったけど
やっぱりそうですよね。。。
※適当なプロジェクトのディレクトリに移動したので./jsディレクトリ以下はちゃんと無数のjsがあります

下記のjsファイルをテスト的に作って再度チャレンジ

- test.js

/**
 * @method testFunction
 * test desuyo.
 * @param aa {String}
 * @param bb {Number}
 * @return cc {String}
 */
var testFunction = function(aa, bb){
  // 特になにもしない
  var cc = 1;
  return cc;
};

# rm -rf docs
# jsduck ./js --output ./docs --title "test desuyo"

そして出来上がった結果がこれ

なるほどー。キレイですね。

とりあえず試しとしてはめでたしめでたし^□^b

補足

エラーになったのでrdiscount.rbを直接編集して絶対パスでrdiscount.soの場所を指定しましたが
locateした結果がおかしかったのでrdiscount.soを移動したら動きました
locate結果

# locate rdiscount.so
/home/hoge/local/lib/ruby/gems/2.0.0/gems/rdiscount-2.1.6/ext/rdiscount.so
/home/hoge/local/lib/ruby/gems/2.0.0/gems/rdiscount-2.1.6/lib/home/hoge/local/lib/ruby/site_ruby/2.0.0/x86_64-linux/rdiscount.so

rdiscount.soを移動

# cp -ap /home/hoge/local/lib/ruby/gems/2.0.0/gems/rdiscount-2.1.6/lib/home/hoge/local/lib/ruby/site_ruby/2.0.0/x86_64-linux/rdiscount.so .

パスの途中で*/home/hoge/local/lib/....と始まってるのでインストールをミスったのかも？

tweeeetyのぶろぐ的めも

アウトプットが少なかったダメな自分をアウトプット<br>＼(＾o＾)／

jsduckでjavascriptドキュメントを作ってみるメモ

はじめに

jsduck入れる

rubyとgem入れる

jsduck入れる

確認

動かすテスト

適当なプロジェクトフォルダでドキュメントを作ってみる

補足