gem annotate の README を翻訳しました

概要

gem annotate の README を翻訳しました。

• 翻訳について

  • 翻訳サービス Deepl と Goole翻訳 の訳文を参考にしている箇所があります。
  • 翻訳対象のコミットハッシュ
  • 非公式の翻訳です。
  • 訳文がおかしい箇所があったら指摘をもらえると幸いです。

• ライセンスについて

  • 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 をご覧ください。