ネオキャリアグループ エンジニアブログ

ネオキャリアグループのエンジニアによるブログです

よう太の冒険: yardとannotateとkramdownでドキュメントに革命を起こす編

こんにちは、こんばんは!
よう太です。

最近、パン屋めぐりという女子っぽい趣味ができました。

さて今回は、yardannotatekramdownを使って、
yardドキュメントにテーブル情報を表示させようと思います。

f:id:Yoko_Takaki:20170331141603j:plain オススメのパン屋さん教えてください

yardとは

Railsアプリケーションに含まれるコードの中に、
コメントを書くことによってドキュメントを作成することができるgemです。

あらかじめyardによって決められたコメントルールに沿って記述し、
yardコマンドを実行すると、ドキュメントを生成することができます。

gemのインストール

まずは必要なgemをインストールします。

yard,annotate,kramdownをGemfileに追加し、
bundle installを実行しましょう。

# Gemfile

gem 'yard'
gem 'annotate'
gem 'kramdown'

yardの基本機能

yardコマンドを実行すると、ドキュメントが作成されます。
例えば、EngineersControllerに以下のようなコメントを記述してみます。

# これはFactoryGirlの記事を書く際に作成したコントローラーです。  
# ちなみにリンクはこちら (´>ω∂`)↓  
# @see http://neo-developers.hatenablog.com/entry/2017/02/17/122249
# @author よう太
  
class EngineersController < ApplicationController
    def create
      engineers_model = Engineer.search_the_most_cakes_ate
    end
end

EngineersControllerを指定して、yardコマンドを実行すると...

f:id:Yoko_Takaki:20170330195750p:plain

このようなドキュメントが生成されます!

EngineersControllerの中に書かれている@see@authorは、
yardであらかじめ決められている「タグ」です。
「タグ」は非常に豊富に用意されているため、また別の機会に取り上げようと思います!
あれっ、前にも同じようなことを書いた覚えが...

代わりと言ってはなんですが、
個人的によく使用するyardコマンド3選をまとめてみました(∩´∀`)∩

# 特定のファイルのみをドキュメント化する場合
$ bundle exec yard doc <ファイル名>

# すべてのファイルをドキュメント化する場合
$ bundle exec yard

# yard-server(http://localhost:8808)を起動する場合
$ bundle exec yard server

各種設定

yardの基本機能を抑えたところで、いよいよ本題に入ります!
yardドキュメントにテーブルを表示させるための設定を行いましょう。

テーブル作成3STEP♡

(1)schemaの出力
(2)マークダウンで出力
(3)マークダウンの適用

(1)schemaの出力

annotateは、Railsアプリケーションのschemaやrootを、
クラスにコメントとして追加してくれるgemです。

annotateをインストールした後、下記のコマンドを実行すると...

$ bundle exec annotate
# == Schema Information
#
# Table name: engineers
#
#  id         :integer          not null, primary key
#  name       :string(255)
#  number     :string(255)
#  section    :string(255)
#  created_at :datetime         not null
#  updated_at :datetime         not null
#

class Engineer < ActiveRecord::Base
  has_many :relation_cakes
  has_many :cakes, through: :relation_cakes
end

このように、schemaが自動的にコメントとして入力されます!
Not Null制限や主キーも記述してくれるなんて、至れり尽くせりですね♡
更に Factoryにもデフォルトでコメントを記述してくれます!

(2)マークダウンで出力

annotateが出力したschemaを、そのままyardコマンドでドキュメント化すると、
以下のように表示されます。

f:id:Yoko_Takaki:20170330203423p:plain

このドキュメントでもテーブルの構成を把握することはできますが、
視認性を上げるために、annotateの出力形式を マークダウン記法 に変更してみます╭( ・ㅂ・)و ✧*。
下記コマンドを実行すると、
annotateの設定ファイルであるlib/tasks/auto_annotate_models.rakeが生成されます。

$ bundle exec rails g annotate:install 

lib/tasks/auto_annotate_models.rakeでは、
annotateのオプションを設定することができます。
lib/tasks/auto_annotate_models.rakeの中に記述されている format_markdown
falseからtrueに変更して、再度bundle exec annotateコマンドを実行すると、
マークダウン記法でschemaが出力されます!

# ## Schema Information
#
# Table name: `engineers`
#
# ### Columns
#
# Name              | Type               | Attributes
# ----------------- | ------------------ | ---------------------------
# **`id`**          | `integer`          | `not null, primary key`
# **`name`**        | `string(255)`      |
# **`number`**      | `string(255)`      |
# **`section`**     | `stringå(255)`      |
# **`created_at`**  | `datetime`         | `not null`
# **`updated_at`**  | `datetime`         | `not null`
#
# ### Indexes
#
# * `index_engineers_on_number` (_unique_):
#     * **`number`**
#

class Engineer < ActiveRecord::Base
  has_many :relation_cakes
  has_many :cakes, through: :relation_cakes
end

(3)マークダウンの適用

yardは、デフォルト設定ではマークダウン記法に対応していないため、
krramdownをインストールして.yardoptsにオプションを記述する必要があります

# .yardopts

--markup markdown
--markup-provider kramdown

.yardoptsファイルを編集してから、
再度yardコマンドを実行すると、整形されたテーブルが表示されます!
やったー!

f:id:Yoko_Takaki:20170330204608p:plain

テーブルの下にコメントを追加したい場合は、
下記のようにコメントアウトした改行を入力してください。

# Table name: `engineers`
#
# ### Columns
#
# Name              | Type               | Attributes
# ----------------- | ------------------ | ---------------------------
# **`id`**          | `integer`          | `not null, primary key`
# **`name`**        | `string(255)`      |
# **`number`**      | `string(255)`      |
# **`section`**     | `string(255)`      |
# **`created_at`**  | `datetime`         | `not null`
# **`updated_at`**  | `datetime`         | `not null`
#
# ### テーブルの下にコメントを書く際は
# - 改行が必須!

コメントアウトせずに改行を入力、
もしくは改行を挟まなかった場合、
ドキュメントに何も表示されなくなってしまうのでご注意ください!

まとめ

今回はannotateとkramdownを使用して、
yardドキュメントにテーブル情報を表示させてみました!
テーブル情報変更された場合も、
annotateコマンドとyardコマンドを実行するだけで簡単に更新できるので、
ぜひぜひお試しください〜