YARD (YARDOC) を Ruby on Rails で使う

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

[![YARD Official WebSite](https://qiita-image-store.s3.amazonaws.com/0/2908/49d6845c-fcff-f83b-333b-e7a2dbe854de.png)](http://yardoc.org/)

- Official : [YARD](http://yardoc.org/)
- RubyGems : [yard | RubyGems.org | your community gem host](https://rubygems.org/gems/yard)
- GitHub : [lsegal/yard](https://github.com/lsegal/yard)
- RubyDoc : [Documentation for yard](http://www.rubydoc.info/gems/yard/frames)

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

----

## Setup

追加するGem

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

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

`/doc` ディレクトリを作成

```shell-session
$ mkdir doc
$ touch doc/.keep
```

gitignore を編集

```:.gitignore
/doc/*
!/doc/.keep
```

YARD のオプション設定

```configuration:.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
```
_[オフィシャル設定](https://github.com/lsegal/yard/blob/master/.yardopts) より引用・改変_

`--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 を利用している場合

下記を追記

```rb: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 を利用している場合

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

```console
$ bundle exec rails g annotate:install
```

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

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

```diff
--- 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](https://qiita.com/HAZI/items/83cc9048c03075888aea)