YARDでrailsのドキュメント作成
Railsのドキュメント作成をする際に、調べ物をしていたらYARDというものがあったので試しに使ってみました。
環境
- ruby 2.2.2p95
- yard 0.8.7.6
- mac 10.10.4
インストール
まずはインストールから。gemからインストールします。
$ gem install yard — no-ri — no-rdoc
Successfully installed yard-0.8.7.6
1 gem installed
使用例
次に今回の使用例です。
ソースに追加
yardには色々なタグで綺麗に出力をする方法が有ります。
まずは簡単な方法でソースコードに追記
変更前例
class ProcessReload
def initialize(program)
case program
when 'httpd'
pid_file = File.join(DEFAULT_ROOT, 'var', 'run', 'httpd', "#{program}.pid")
when 'drweb-monitor'
pid_file = File.join(DEFAULT_ROOT, 'var', 'drweb', 'run', "#{program}.pid")
end
@pid = File.open(pid_file, "r").read.chomp.to_i
end
def reload
Process.kill(:HUP, @pid)
end
end
変更後
class ProcessReload
# initialize method
# @param [String] program 再起動するプロセス名(現在はhttpdとdrweb-monitorのみ)
def initialize(program)
case program
when 'httpd'
pid_file = File.join(DEFAULT_ROOT, 'var', 'run', 'httpd', "#{program}.pid")
when 'drweb-monitor'
pid_file = File.join(DEFAULT_ROOT, 'var', 'drweb', 'run', "#{program}.pid")
end
@pid = File.open(pid_file, "r").read.chomp.to_i
end
# @pidに格納したプロセスの再起動
def reload
Process.kill(:HUP, @pid)
end
end
この雰囲気で修正し実行してみました。
ドキュメント作成コマンドを実行
$ yardoc lib/hosting/hosting_process.rb
Files: 1
Modules: 1 ( 1 undocumented)
Classes: 1 ( 1 undocumented)
Constants: 0 ( 0 undocumented)
Methods: 2 ( 0 undocumented)
50.00% documented
すると doc/ ができています。
$ ls -R doc
Hosting file_list.html
Hosting.html frames.html
_index.html index.html
class_list.html js
css method_list.html
file.README.html top-level-namespace.html
doc/Hosting:
HostingProcess.html
doc/css:
common.css full_list.css style.css
doc/js:
app.js full_list.js jquery.js
するとこんなかんじにページが出来てます。
すごー。
Railsの単位でドキュメントを作成してみる
Rakeタスクを使う方法が紹介されていました。
Gemfileに追加
Gemfile
gem 'yard', group: :doc
その後 bundle install します
taskファイルを作成
lib/tasks/yarddoc.rake
require 'yard'
require 'yard/rake/yardoc_task'
namespace :doc do
YARD::Rake::YardocTask.new do |t|
t.files = %w(
app/models/**/*.rb
app/controllers/**/*.rb
app/helpers/**/*.rb
app/mailers/**/*.rb
lib/**/*.rb
)
t.options = []
# t.options = %w(--debug --verbose) if $trace
end
end
すると
$ rake -T |grep yard
rake doc:yard # Generate YARD Documentation
と実行できるようになるのでyardの書式を特に追加せずにやってみます。
実行する際は rails のトップ階層で行います。
$ rake doc:yard
### 特にyardに対応した方法でなにも書かずに実行したので結構エラーが。
Files: 247
Modules: 92 ( 73 undocumented)
Classes: 324 ( 153 undocumented)
Constants: 459 ( 93 undocumented)
Methods: 3600 ( 443 undocumented)
82.97% documented
こんな感じでアウトプットされます。
GCとか自分が書いた物以外も出力されてしまっているのでこれをどうにかしたい。
トップにmarkdownがあるとインデックスファイルにそれを表示してくれるのすごいですね。
参考記事
ありがとうございます。
[http://blog.falconsrv.net/articles/449](http://blog.falconsrv.net/articles/449)