YARDでrailsのドキュメント作成

2015年7月29日

ETC

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

環境

インストール

使用例

ソースに追加

共有: