YARD (YARDOC) を Ruby on Rails で使う

今まで適当に rdoc で誤魔化していたが、さすがにあれなので 今更 YARD を Ruby on Rails のプロジェクトに導入してみました。

• Official : YARD
• RubyGems : yard | RubyGems.org | your community gem host
• GitHub : lsegal/yard
• RubyDoc : Documentation for yard

YARD は RubyDoc などでよく見かけるスタイルの HTML形式のドキュメント生成ツールです。

---

Setup

追加するGem

Gemfile

group :development do
  gem 'yard'
  gem 'guard-yard'
  gem 'yard-activesupport-concern' # Rails で Concern 使う場合は必須
  gem 'redcarpet' # Option (Markdown)
end

• gem guard-yard は Guard でファイル変更を検知すると yard のドキュメントも更新してくれる（ただし挙動が微妙詳細は後記）
• gem redcarpet は Makrdown 形式へ対応するためのもの。
  • gem annotate などの自動生成ツールで makrdown を利用している人は必須。

/doc ディレクトリを作成

$ mkdir doc
$ touch doc/.keep

gitignore を編集

.gitignore

/doc/*
!/doc/.keep

YARD のオプション設定

.yardopts

--protected
--no-private
--markup markdown # markdown で書けるようになる
#--markup-provider redcarpet # v0.7.4 から不要
#--exclude /lib/tasks # 不要なディレクトリを指定
#--asset docs/images:images # ドキュメントで利用したい画像などがある場合
--plugin activesupport-concern # Rails で Concern 使う場合は必須
#--load ./docs/templates/plugin.rb # 自作プラグインがある場合
-
# テキストドキュメントがある場合は以下に羅列
#CHANGELOG.md
#docs/WhatsNew.md
#docs/GettingStarted.md

オフィシャル設定 より引用・改変

--markup markdown はデフォルトで指定されるようになったらしいが、一部 `code` などの記法が使えないことがあったので、指定している。

--markup-provider は redcarpet がインストールされている場合は自動で redcarpet が選択される。

--exclude は基本的には不要で、ディレクトリを指定しないで実行した場合は、lib/**/*.rb, app/**/*.rb, ext/**/*.c がドキュメント生成の対象となるので、それらから除きたいファイルがある場合のみ指定すれば OK。

インストール & 実行

$ bundle install
$ bundle exec yard

$ bundle exec yard server
or
$ open doc/index.html

これで ./doc 下に html ファイルが生成される。

yard server, yard doc

アプリケーションが大きくなると、修正するたびに yard を実行すると時間がかかってたまらない。

bundle exec yard server --reload

server --reload オプションを使うとアクセスするたびにファイルの内容を反映してくれるのでブラウザをリロードするだけでドキュメントを確認できる。

ただし、注意点があってメソッドを削除しても反映されなかったりと、項目が減った場合などに反映がうまく行われない。

特に @!macro などで大量にドキュメントを自動生成させるときは、ミスした後修正しても誤ったドキュメントがそのまま残って混乱することがあるので注意が必要。

そういった場合は doc オプションを使って特定のファイルだけ作り直しを実行させると、解決する。

bundle exec yard doc [FILE PATH]

Guard を利用している場合

下記を追記

Guardfile

group :yard do
  guard 'yard' do
    watch(%r{app/.+\.rb})
    watch(%r{lib/.+\.rb})
  end
end

これで guard 実行時に、デフォルトでは http://0.0.0.0:8808 にアクセスすれば、yard serverにアクセスできる。

最初にも書いたが挙動が微妙で、他のファイルへのリンクなどが壊れることがある。なので、guard は使わずに、yard server --reload の方がいいと思う。

Annotate を利用している場合

下記のコマンドを実行してなければ実行。

$ bundle exec rails g annotate:install

これで、rake db:migrate 時に自動的に annotate のスキーマ情報が更新される。

次にフォーマットを markdown に変更。

--- a/lib/tasks/auto_annotate_models.rake
+++ b/lib/tasks/auto_annotate_models.rake
@@ -21,9 +21,9 @@ if Rails.env.development?
       'exclude_factories'    => 'false',
       'ignore_model_sub_dir' => 'false',
       'skip_on_db_migrate'   => 'false',
-      'format_bare'          => 'true',
+      'format_bare'          => 'false',
       'format_rdoc'          => 'false',
-      'format_markdown'      => 'false',
+      'format_markdown'      => 'true',

もし、rake db:migrate 時に自動的に実行したくなければ skip_on_db_migrate を 'true' にすればいいはず。

これで、annotate のスキーマ情報もちゃんと yard の html に表示されるようになる。

関連記事

• YARD macro を使った Rails scope のドキュメントの書き方 - Qiita