Ruby
Rails
Guard
YARD
annotate

今更 YARD (YARDOC) を Ruby on Rails で使う

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

YARD Official WebSite

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-providerredcarpet がインストールされている場合は自動で 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 ファイルが生成される。

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 に表示されるようになる。

関連記事