概要
gem annotate の README を翻訳しました。
-
翻訳について
-
ライセンスについて
- annotate のライセンスと同様に、BSD ライセンスに従います。
オプションの目次
--additional-file-patterns
-d, --delete
-p [before|top|after|bottom], --position
--pc, --position-in-class [before|top|after|bottom]
--pf, --position-in-factory [before|top|after|bottom]
--px, --position-in-fixture [before|top|after|bottom]
--pt, --position-in-test [before|top|after|bottom]
--pr, --position-in-routes [before|top|after|bottom]
--ps, --position-in-serializer [before|top|after|bottom]
--w, --wrapper STR
--wo, --wrapper-open STR
--wc, --wrapper-close STR
-r, --routes
--models
-a, --active-admin
-v, --version
-m, --show-migration
-k, --show-foreign-keys
--ck, --complete-foreign-keys
-i, --show-indexes
-s, --simple-indexes
--model-dir dir
--root-dir dir
--ignore-model-subdirects
--sort
--classified-sort
-R, --require path
-e [tests,fixtures,factories,serializers], --exclude
-f [bare|rdoc|yard|markdown], --format
--force
--frozen
--timestamp
--trace
-I, --ignore-columns REGEX
--ignore-routes REGEX
--hide-limit-column-types VALUES
--hide-default-column-types VALUES
--ignore-unknown-models
--with-comment
- オプション:
additional_file_patterns
Annotate (aka AnnotateModels)
下記のファイルの上部あるいは下部に現在の DB スキーマを要約したコメントを追加します。
- ActiveRecord models
- Fixture files
- Tests and Specs
- Object Daddy exemplars
- Machinist blueprints
- Fabrication fabricators
- Thoughtbot's factory_bot factories, i.e. the
(spec|test)/factories/<model>_factory.rb
files -
routes.rb
file (for Rails projects)
スキーマコメントは下記のように記載されます。
# == Schema Info
#
# Table name: line_items
#
# id :integer(11) not null, primary key
# quantity :integer(11) not null
# product_id :integer(11) not null
# unit_price :float
# order_id :integer(11)
#
class LineItem < ActiveRecord::Base
belongs_to :product
. . .
また、SpatialAdapter
, PostgisAdapter
, PostGISAdapter
のいずれかを使用したときは、geom
タイプや srid
タイプのような幾何学的なカラムにも注釈をつけます。
# == Schema Info
#
# Table name: trips
#
# local :geometry point, 4326
# path :geometry line_string, 4326
また、-r
オプションを渡すと、rake routes
の出力を routes.rb
にコメントとして追加します。
3.Xにアップグレードするとモデルへの注釈が動作しない?
バージョン 2.7.X では、引数が何も渡されない場合は、gem annotate はデフォルトでモデルに注釈を追加していました。
デフォルトでは、gem annotate は routes とモデルが一緒に注釈を追加されることを許可していません。
#647 で変更が追加されました。
詳細はこちらでご覧ください。
この問題を修正する方法はいくつかあります。
- CLI を使用している場合は、
--models
を使用してモデルフラグを明示的に渡してください。
あるいは
a) rails g annotate:install
を実行し、デフォルト設定が models
オプション 'true'
になるように上書きします。
b) lib/tasks/auto_annotate_models.rake
において models
のキーと値を追加します。
Annotate.set_defaults(
...
'models' => 'true',
...
インストール
rubygems.org から 追加
group :development do
gem 'annotate'
end
Github から 追加
group :development do
gem 'annotate', git: 'https://github.com/ctran/annotate_models.git'
end
rubygems.org からインストール
gem install annotate
Github のチェックアウトからインストール
git clone https://github.com/ctran/annotate_models.git annotate_models
cd annotate_models
rake build
gem install pkg/annotate-*.gem
利用方法
もし Gemfile 経由でインストールをしているなら、bundle exec
を下記コマンドにつけてください。
Rails での利用方法
すべてのモデル、テスト、フィクスチャ、ファクトリに注釈をつける。
cd /path/to/app
annotate
モデル、テスト、ファクトリのみに注釈をつける。
annotate --models --exclude fixtures
モデルのみに注釈をつける。
annotate --models
routes.rb に注釈をつける。
annotate --routes
モデル、テスト、フィクスチャ、ファクトリ、シリアライザの注釈を削除する。
annotate --delete
routes.rb の注釈を削除する。
annotate --routes --delete
db:migrate
を実行するたびに自動的に注釈をつけるためには、
rails g annotate:install
を実行するか、Rakefile
に Annotate.load_tasks
を追加してください。
詳細は Rails における設定 をご覧ください。
Rails の外での利用方法
--routes
オプションが意味をなさないことを除けば Rails 外の利用でも上述のすべてが適用されます。明示的に1つあるいは複数の --require
オプションと --model-dir
オプションを設定することで、annotate
にプロジェクトの構造を知らせ、プロジェクトが起動し関連のあるコードを読み込むことを助ける必要があります。
設定
もし特定のモデルで注釈を常に飛ばしたいときは、モデルファイルの任意の場所に下記の文字列を追加してください。
# -*- SkipSchemaAnnotations
Rails における設定
設定ファイル(.rake
ファイル形式)を生成して、デフォルトオプションを設定するためには下記のコマンドを実行してください。
rails g annotate:install
このファイルを編集することで、注釈がファイルの上下どちらに追加されるかや、どのタイプのファイルに注釈が記載されるかといったような、出力形式などを制御します。
生成される rake ファイルである lib/tasks/auto_annotate_models.rake
は Annotate.load_tasks
も含みます。この rake ファイルはコマンドラインの機能と重複するいくつかの rake タスクを追加します。
rake annotate_models # Add schema information (as comments) to model and fixture files
rake annotate_routes # Adds the route map to routes.rb
rake remove_annotation # Remove schema information from model and fixture files
デフォルトでは、一旦設定ファイルを生成したあとは、rake db:migrate
が実行されるたびに annotate が実行されます(development 環境のみ)。
この挙動を永続的に無効にしたいときは、.rake
ファイルを編集し、下記のように変更してください。
'skip_on_db_migrate' => 'false',
上記の記述から下記の記述へ変更する。
'skip_on_db_migrate' => 'true',
1回だけ annotate なしで rake db:migrate
を実行したいときは、.rake
ファイルを編集する代わりにシンプルな環境変数をつけることでそれを実現できます。
ANNOTATE_SKIP_ON_DB_MIGRATE=1 rake db:migrate
オプション
--additional-file-patterns
コンマで区切った注釈を行う追加のファイルパスあるいは glob(例: /foo/bar/%model_name%/*.rb,/baz/%model_name%.rb
)を記載する。
-d, --delete
すべてのモデルファイルあるいは routes.rb ファイルから注釈を削除する。
-p [before|top|after|bottom], --position
model/test/fixture/factory/route/serializer ファイルの上部(前)あるいは下部(後)に注釈を置く。
--pc, --position-in-class [before|top|after|bottom]
model ファイルの上部(前)あるいは下部(後)に注釈を置く。
--pf, --position-in-factory [before|top|after|bottom]
factory ファイルの上部(前)あるいは下部(後)に注釈を置く。
--px, --position-in-fixture [before|top|after|bottom]
fixture ファイルの上部(前)あるいは下部(後)に注釈を置く。
--pt, --position-in-test [before|top|after|bottom]
test ファイルの上部(前)あるいは下部(後)に注釈を置く。
--pr, --position-in-routes [before|top|after|bottom]
routes.rb ファイルの上部(前)あるいは下部(後)に注釈を置く。
--ps, --position-in-serializer [before|top|after|bottom]
serializer ファイルの上部(前)あるいは下部(後)に注釈を置く。
--w, --wrapper STR
パラメーターとして渡されたテキストで注釈をラップします。
--w が使用された場合は、同じテキストが始端と終端に使用されます。
--wo, --wrapper-open STR
注釈の始端をラップするテキスト。
--wc, --wrapper-close STR
注釈の終端をラップするテキスト。
-r, --routes
'rake routes' の出力で routes.rb に注釈を付ける。
--models
ActiveRecord モデルに注釈を付ける。
-a, --active-admin
active_admin モデルに注釈を付ける。
-v, --version
この gem の現在のバージョンを表示する。
-m, --show-migration
注釈にマイグレーションのバージョン番号を含める。
-k, --show-foreign-keys
注釈にテーブルの外部キー制約の一覧を載せる。
--ck, --complete-foreign-keys
注釈に完全な外部キーの名前を載せる。
-i, --show-indexes
注釈にテーブルのインデックスの一覧を載せる。
-s, --simple-indexes
注釈内のカラムの関連したインデックスを結合する。
--model-dir dir
app/models ではないディレクトリに保存されたモデルファイルに注釈を付ける。ディレクトリ名はカンマで区切る。
--root-dir dir
ルートディレクトリのプロジェクト内に保存されたファイルに注釈を付ける。ディレクトリ名はカンマで区切る。
--ignore-model-subdirects
モデルディレクトリのサブディレクトリを無視する。
--sort
作成順ではなくアルファベット順でカラムをソートする。
--classified-sort
アルファベット順にカラムをソートする。ただし、一番目には id 、その次が残りのカラム、タイムスタンプカラム、関連付けカラムの順となる。
-R, --require path
モデルを読み込む前に必要とする追加のファイル。このファイルは複数回使用される。
-e [tests,fixtures,factories,serializers], --exclude
tests,fixtures,factories,serializers ファイルに注釈を付けないようにする。
-f [bare|rdoc|yard|markdown], --format
プレインテキスト/RDoc/YARD/Markdown としてスキーマ情報を記述する。
--force
変更がない場合でも新しい注釈を強制的に記述する。
--frozen
注釈の変更を許可しない。ファイルに変更がある場合は、ゼロ以外の値で終了します。
--timestamp
注釈にタイムスタンプを含ませる。
--trace
ファイルに注釈を付けられない場合は、例外メッセージだけでなく、スタックトレース全体を表示する。
-I, --ignore-columns REGEX
与えられた正規表現に合致するカラムに注釈をつけないようにする(例: annotate -I '^(id|updated_at|created_at)'
)。
--ignore-routes REGEX
与えられた正規表現に合致する routes に注釈をつけないようにする(例: annotate -I '(mobile|resque|pghero)'
)。
--hide-limit-column-types VALUES
与えられたカラムタイプに limit 値を表示させない。カラムタイプはコンマで区切る(例: integer,boolean,text
)。
--hide-default-column-types VALUES
与えられたカラムタイプに default 値を表示させない。カラムタイプはコンマで区切る(例: json,jsonb,hstore
)。
--ignore-unknown-models
不正なモデルファイルに対して警告を表示させない。
--with-comment
モデルの注釈にデータベースコメントを含める。
オプション: additional_file_patterns
CLI: --additional-file-patterns
Ruby: :additional_file_patterns
注釈を行うために追加のパスを提供します。このパスは glob を含むことができます。絶対パスを使用することを推奨します。下記に例を記載します。
/app/lib/decorates/%MODEL_NAME%/*.rb
/app/lib/forms/%PLURALIZED_MODEL_NAME%/**/*.rb
/app/lib/forms/%TABLE_NAME%/*.rb
適切なモデルは %*%
構文を用いて推論され、一致するファイルに注釈が付けられます。これは既存のファイル名解決とともに動作します(annotate_models.rb
の resolve_filename
メソッドの中で発見されるオプション)。
Rails の設定の中で使用するときは、下記を使用できます。
File.join(Rails.application.root, 'app/lib/forms/%PLURALIZED_MODEL_NAME%/***/**.rb')
ソート
デフォルトでは、カラムはデータベース順でソートされます(つまりマイグレーションが行われた順番)。
もしアルファベット順にソートしてマイグレーションを実行した順番とは関係なく注釈の結果を一致させたいときは、--sort
オプションを使用してください。
マークダウン
生成されるフォーマットは実際には MultiMarkdown で、テーブルのための構文拡張機能を利用しています。もしこのフォーマットを使用したいときはパーサーとして kramdown
を使用することを推奨しています。もしドキュメントを生成するために yard
を使用している場合は、.yardopts
ファイルに kramdown
を追加することでプロバイダとして kramdown
をマークダウンのフォーマットに指定してください。
--markup markdown
--markup-provider kramdown
Gemfile
にも同様に kramdown を追加するようにしてください。
gem 'kramdown', groups => [:development], require => false
警告
**自動作成されたコメントブロックの後にテキストを追加しないでください。**annotate によって以前にコメントブロックが追加された可能性があるとき、annotate はモデル内の始端・終端のコメントブロックを削除することがあります。
annotate が行った変更を必ず確認するようにしてください。Git を使用している場合は、annotate
を実行した後にプロジェクトのステータスを確認することができます。
$ git status
VCS(Git や Subversion など)を使っていない人は、特に注意して annotate を扱い、1つの VCS の利用を検討してください。
リンク集
- Factory Bot: http://github.com/thoughtbot/factory_bot
- Object Daddy: http://github.com/flogic/object_daddy
- Machinist: http://github.com/notahat/machinist
- Fabrication: http://github.com/paulelliott/fabrication
- SpatialAdapter: http://github.com/pdeffendol/spatial_adapter
- PostgisAdapter: http://github.com/nofxx/postgis_adapter
- PostGISAdapter: https://github.com/dazuma/activerecord-postgis-adapter
ライセンス
Ruby と同じライセンスでリリースしています。サポートと保証はありません。
作者
AUTHORS.md をご覧ください。