Skip to content

A
annotate
Commit cb09e6aa by Vasily Fedoseyev Committed by Andrew W. Lee
Options

Convert documentation files to Markdown (#697)

* Convert documentation files to Markdown * Add notice about models not being annotated by default to changelog in 3.0
parent d16182f6
Showing with 401 additions and 381 deletions
.document
spec/**/*.rb
lib/**/*.rb
-
README.rdoc
CHANGELOG.rdoc
TODO.rdoc
README.md
CHANGELOG.md
TODO.md
AUTHORS.rdoc → AUTHORS.md
== Authors
## Authors
- Original code by: Dave Thomas -- Pragmatic Programmers, LLC <http://agilewebdevelopment.com/plugins/annotate_models>
- Overhauled by: Alex Chaffee <http://alexch.github.com> alex@stinky.com
......@@ -6,7 +6,7 @@
- Maintained by: Alex Chaffee and Cuong Tran
- Homepage: http://github.com/ctran/annotate_models
With help from:
### With help from:
- Jack Danger - http://github.com/JackDanger
- Michael Bumann - http://github.com/bumi
......
CHANGELOG.md 0 → 100644
## 3.0.3
- Use a less error-prone way of specifying gem files (#662)
- Update rake requirement from `>= 10.4, < 13.0` to `>= 10.4, < 14.0` (#659)
- Bump nokogiri from 1.6.6.2 to 1.10.4 in /spec/integration/rails_4.2.0 (#655)
- Default annotate models to true in config generated by `rails g annotate:install` (#671)
- Bump loofah from 2.3.0 to 2.3.1 in /spec/integration/rails_4.2.0 (#681)
## 3.0.2
- Fixes `LoadError` due to gemspec not referencing `parser.rb`, issue #657 (#660)
- Changes `--additional_file_patterns` to use dashes `--additional-file-patterns` for consistency (#649)
- Refactor: moving constants into `constants.rb` (#653)
## 3.0.1
- Skipped as an official release, used the 3.0.1 patch for setting up Github Actions (#619)
## 3.0.0
- **Breaking:** when option `models` is not set - models will not be annotated by default.
Add `'models'=>'true'` to your config manually or use `--models` option if using CLI.
- Added `--models` CLI option fixing issue #563 (#647)
- Added `--additional_file_patterns` option for additional file patterns (#633) (#636) (#637)
- Refactored CLI parser (#646)
- Fixed `BigDecimal.new` deprecation warning (#634)
- Fixed annotations for columns with long data types (#622)
- Made methods private in AnnotateRoutes (#598)
See https://github.com/ctran/annotate_models/releases/tag/v3.0.0
## 2.7.5
See https://github.com/ctran/annotate_models/releases/tag/v2.7.5
## 2.7.3
See https://github.com/ctran/annotate_models/releases/tag/v2.7.3
## 2.7.2
See https://github.com/ctran/annotate_models/releases/tag/v2.7.2
## 2.7.1
See https://github.com/ctran/annotate_models/releases/tag/v2.7.1
## 2.7.0
See https://github.com/ctran/annotate_models/releases/tag/v2.7.0
## 2.6.9
- Support foreigh key (#241)
- Check if model has skip tag in annotate_model_file (#167)
- Fix issue where serializer-related flags weren't being honored (#246)
- Prefer SQL column type over normalized AR type (#231)
## 2.6.8
- Nothing annotated unless `options[:model_dir]` is specified, #234
## 2.6.7
- Nothing annotated unless `options[:model_dir]` is specified, #234
## 2.6.6
- Makes it possible to wrap annotations, #225
- Fix single model generation, #214
- Fix default value for Rails 4.2, #212
- Don't crash on inherited models in subdirectories, #232
- Process model_dir in rake task, #197
## 2.6.4
- Skip "models/concerns", #194
- Fix #173 where annotate says "Nothing to annotate" in rails 4.2
- Display an error message if not run from the root of the project, #186
- Support rails 4.0 new default test directory, #182
- Add an option to show timestamp in routes "-timestamp", #136
- Skip plain ruby objects if they have the same class name as an ActiveRecord object, #121
## 2.6.3
- Fix bug of annotate position in routes (#158)
## 2.6.2
- Retain the current annotate block unless --force is specified
- Always load models, since they may not be autoloaded by Rails
- The pg array type is now detected (see #158)
## 2.6.0.beta2
- support for composite_primary_keys (garysweaver)
- bug fix for annotate_one_file (vlado)
## 2.6.0.beta1
- It's now possible to use Annotate in standalone ActiveRecord (non-Rails) projects again.
- Adding note that Markdown is actually MultiMarkdown, and recommending the use
of the `kramdown` engine for parsing it.
- Improved Markdown formatting considerably.
- Bugfix: Needed to use inline-code tag for column and table names,
otherwise underscores would cause havok with the formatting.
- Bugfix: Markdown syntax was incorrect
(can't have trailing spaces before the closing marker for an emphasis tag).
- Bugfix: Remove-annotations wasn't properly finding test/spec files,
and wasn't even looking for FactoryGirl factories under the new naming convention.
- Bugfix: Load the Rakefile from the current directory, not the first
Rakefile in our load path.
- Added support for new FactoryGirl naming convention.
- Fix behavior of route annotations in newer versions of Rake that don't
spit out the CWD as their first line of output.
- Overhauled integration testing system to be much easier to work with,
better compartmentalized, and so forth -- at the cost that you must be
using RVM to utilize it. (It'll spit out appropriate pending messages if
you don't.) Also includes a mode for "tinkering" by hand with a scenario,
and won't let you run it through rspect if the repo is in a dirty state.
Added appropriate rake tasks to help with all of this.
- Routes can now be appended, pre-pended, or removed -- and do sane things in all cases.
- Expose all `position_*` variables as CLI params.
- Make `ENV ['position']` work as a default for all the `ENV ['position_*']` variables.
- Make rake tasks more resilient to unusual circumstances / code loading behavior.
- Resolve annotate vs. annotate_models ambiguity once and for all by
settling on `annotate_models` *and* `annotate_routes`. This avoids a name
collision with RMagick while not needlessly overloading the term.
- Fixed that schema kept prepending additional newlines
- Updates to make annotate smarter about when to touch a model
- Recognize column+type, and don't change a file unless the column+type
combination of the new schema are different than that of the old (i.e.,
don't regenerate if columns happen to be in a different order. That's just
how life is sometimes)
- Change annotate to use options hash instead of ENV.
## 2.5.0
- Works better with Rails 3
- Bugfix: schema kept prepending additional newlines
- Updates to make annotate smarter about when to touch a model
- Recognize column+type, and don't change a file unless the column+type
combination of the new schema are different than that of the old (i.e.,
don't regenerate if columns happen to be in a different order. That's just
how life is sometimes.)
- Grab old specification even if it has `\r\n` as line endings rather than pure `\n`s
- Various warning and specification fixes
- Fix "no such file to load -- annotate/annotate_models (MissingSourceFile)"
error (require statements in tasks now use full path to lib files)
- warn about macros, to mitigate when we're included during a production
run, not just a rakefile run -- possibly at the expense of too much noise
- Adding rake as a runtime dependency
- If the schema is already in the model file, it will be replaced into the same location.
If it didn't previously exist, it'll be placed according to the "position", as before.
- Allow task loading from Rakefile for gems (plugin installation already auto-detects).
- Add skip_on_db_migrate option as well for people that don't want it
- Fix options parsing to convert strings to proper booleans
- Add support for Fabrication fabricators
- Leave magic encoding comment intact
- Fix issue #14 - RuntimeError: Already memoized
- Count a model as 'annotated' if any of its tests/fixtures are annotated
- Support FactoryGirl
- Support :change migrations (Rails 3.1)
- Allow models with non-standard capitalization
- Widen type column so we can handle longtexts with chopping things off.
- Skip trying to get list of models from commandline when running via Rake
(was preventing the use of multiple rake tasks in one command if one of them was `db:migrate`).
- Add ability to skip annotations for a model by adding
`# -*- SkipSchemaAnnotations` anywhere in the file.
- Don't show column limits for integer and boolean types.
- Add sorting for columns and indexes.
(Helpful for out-of-order migration execution. Use `--sort` if you want this.)
- Annotate unit tests in subfolders.
- Add generator to install rakefile that automatically annotates on `db:migrate`.
- Correct Gemfile to clarify which environments need which gems.
- Add an .rvmrc to facilitate clean development.
- Refactor out ActiveRecord monkey-patch to permit extending without side-effects.
- Use ObjectSpace to locate models to facilitate handling of models with
non-standard capitalization.
Note that this still requires that the inflector be configured to understand
the special case.
- Shore up test cases a bit.
- Merge against many of the older branches on Github whose functionality is
already reflected to reduce confusion about what is and is not implemented here.
- Accept String or Symbol for :position (et al) options.
- Add RDoc output formatting as an option.
- Add Markdown output formatting as an option.
- Add option to force annotation regeneration.
- Add new configuration option for controlling where info is placed in
fixtures/factories.
- Fix for models without tables.
- Fix gemspec generation now that Jeweler looks at Gemfile.
- Fix warning: `NOTE: Gem::Specification#default_executable= is deprecated
with no replacement. It will be removed on or after 2011-10-01.`
- Fix handling of files with no trailing newline when putting annotations at
the end of the file.
- Now works on tables with no primary key.
- `--format=markdown` option
- `--trace` option to help debug "Unable to annotate" errors
- "Table name" annotation (if table name is different from model name)
- "Human name" annotation (enabling translation to non-English locales)
- Fix JRuby ObjectSpace compatibility bug (https://github.com/ctran/annotate_models/pull/85)
- Fix FactoryGirl compatibility bug (https://github.com/ctran/annotate_models/pull/82)
## 2.4.2 2009-11-21
- Annotates `(spec|test)/factories/<model>_factory.rb` files
## 2.4.1 2009-11-20
- Annotates thoughtbot's factory_girl factories (`test/factories/<model>_factory.rb`)
- Move default annotation position back to top
## 2.4.0 2009-12-13
- Incorporated lots of patches from the Github community,
including support for Blueprints fixtures
- Several bug fixes
## 2.1 2009-10-18
- New options
- `-R` to require additional files before loading the models
- `-i` to show database indexes in annotations
- `-e` to exclude annotating tests or fixtures
- `-m` to include the migration version number in the annotation
- `--model-dir` to annotate model files stored a different place than `app/models`
- Ignore unknown macros ('acts_as_whatever')
## 2.0 2009-02-03
- Add annotate_models plugin fork additions
- Annotates Rspec and Test Unit models
- Annotates Object Daddy exemplars
- Annotates geometrical columns
- Add AnnotateRoutes rake task
- Up gem structure to newgem defaults
## 1.0.4 2008-09-04
- Only update modified models since last run, thanks to sant0sk1
## 1.0.3 2008-05-02
- Add misc changes from Dustin Sallings and Henrik N
- Remove trailing whitespace
- More intuitive info messages
- Update README file with update-to-date example
## 1.0.2 2008-03-22
- Add contributions from Michael Bumann (http://github.com/bumi)
- added an option "position" to choose to put the annotation,
- spec/fixtures now also get annotated
- added a task to remove the annotations
- these options can be specified from command line as `-d` and `-p [before|after]`
CHANGELOG.rdoc deleted 100644 → 0
== 3.0.3
* Use a less error-prone way of specifying gem files (#662)
* Update rake requirement from >= 10.4, < 13.0 to >= 10.4, < 14.0 (#659)
* Bump nokogiri from 1.6.6.2 to 1.10.4 in /spec/integration/rails_4.2.0 (#655)
* Defaults annotate models to true (#671)
* Bump loofah from 2.3.0 to 2.3.1 in /spec/integration/rails_4.2.0 (#681)
== 3.0.2
* Fixes `LoadError` due to gemspec not referencing `parser.rb`, issue #657 (#660)
* Changes `--additional_file_patterns` to use dashes `--additional-file-patterns` for consistency (#649)
* Refactor: moving constants into `constants.rb` (#653)
== 3.0.1
* Skipped as an official release, used the 3.0.1 patch for setting up Github Actions (#619)
== 3.0.0
* Added `--models` CLI option fixing issue #563 (#647)
* Added `--additional_file_patterns` option for additional file patterns (#633) (#636) (#637)
* Refactored CLI parser (#646)
* Fixed BigDecimal.new deprecation warning (#634)
* Fixed annotations for columns with long data types (#622)
* Made methods private in AnnotateRoutes (#598)
See https://github.com/ctran/annotate_models/releases/tag/v3.0.0
== 2.7.5
See https://github.com/ctran/annotate_models/releases/tag/v2.7.5
== 2.7.3
See https://github.com/ctran/annotate_models/releases/tag/v2.7.3
== 2.7.2
See https://github.com/ctran/annotate_models/releases/tag/v2.7.2
== 2.7.1
See https://github.com/ctran/annotate_models/releases/tag/v2.7.1
== 2.7.0
See https://github.com/ctran/annotate_models/releases/tag/v2.7.0
== 2.6.9
* Support foreigh key (#241)
* Check if model has skip tag in annotate_model_file (#167)
* Fix issue where serializer-related flags weren't being honored (#246)
* Prefer SQL column type over normalized AR type (#231)
== 2.6.8
* Nothing annotated unless options[:model_dir] is specified, #234
== 2.6.7
* Nothing annotated unless options[:model_dir] is specified, #234
== 2.6.6
* Makes it possible to wrap annotations, #225
* Fix single model generation, #214
* Fix default value for Rails 4.2, #212
* Don't crash on inherited models in subdirectories, #232
* Process model_dir in rake task, #197
== 2.6.4
* Skip "models/concerns", #194
* Fix #173 where annotate says "Nothing to annotate" in rails 4.2
* Display an error message if not run from the root of the project, #186
* Support rails 4.0 new default test directory, #182
* Add an option to show timestamp in routes "-timestamp", #136
* Skip plain ruby objects if they have the same class name as an ActiveRecord object, #121
== 2.6.3
* Fix bug of annotate position in routes (#158)
== 2.6.2
* Retain the current annotate block unless --force is specified
* Always load models, since they may not be autoloaded by Rails
* The pg array type is now detected (see #158)
== 2.6.0.beta2
* support for composite_primary_keys (garysweaver)
* bug fix for annotate_one_file (vlado)
== 2.6.0.beta1
* It's now possible to use Annotate in standalone ActiveRecord (non-Rails)
projects again.
* Adding note that Markdown is actually MultiMarkdown, and recommending the use
of the `kramdown` engine for parsing it.
* Improved Markdown formatting considerably.
* Bugfix: Needed to use inline-code tag for column and table names, otherwise
underscores would cause havok with the formatting.
* Bugfix: Markdown syntax was incorrect (can't have trailing spaces before the
closing marker for an emphasis tag).
* Bugfix: Remove-annotations wasn't properly finding test/spec files, and
wasn't even looking for FactoryGirl factories under the new naming
convention.
* Bugfix: Load the Rakefile from the current directory, not the first Rakefile
in our load path.
* Added support for new FactoryGirl naming convention.
* Fix behavior of route annotations in newer versions of Rake that don't spit
out the CWD as their first line of output.
* Overhauled integration testing system to be much easier to work with, better
compartmentalized, and so forth -- at the cost that you must be using RVM to
utilize it. (It'll spit out appropriate pending messages if you don't.)
Also includes a mode for "tinkering" by hand with a scenario, and won't let
you run it through rspect if the repo is in a dirty state. Added appropriate
rake tasks to help with all of this.
* Routes can now be appended, pre-pended, or removed -- and do sane things in
all cases.
* Expose all `position_*` variables as CLI params.
* Make `ENV ['position']` work as a default for all the `ENV ['position_*']`
variables.
* Make rake tasks more resilient to unusual circumstances / code loading
behavior.
* Resolve annotate vs. annotate_models ambiguity once and for all by settling
on `annotate_models` _and_ `annotate_routes`. This avoids a name collision
with RMagick while not needlessly overloading the term.
* Fixed that schema kept prepending additional newlines
* Updates to make annotate smarter about when to touch a model
* Recognize column+type, and don't change a file unless the column+type
combination of the new schema are different than that of the old (i.e., don't
regenerate if columns happen to be in a different order. That's just how life
is sometimes)
* Change annotate to use options hash instead of ENV.
== 2.5.0
* Works better with Rails 3
* Bugfix: schema kept prepending additional newlines
* Updates to make annotate smarter about when to touch a model
* Recognize column+type, and don't change a file unless the column+type combination of the new schema are different than that of the old (i.e., don't regenerate if columns happen to be in a different order. That's just how life is sometimes.)
* Grab old specification even if it has \r\n as line endings rather than pure \ns
* Various warning and specification fixes
* Fix "no such file to load -- annotate/annotate_models (MissingSourceFile)"
error (require statements in tasks now use full path to lib files)
* warn about macros, to mitigate when we're included during a production run,
not just a rakefile run -- possibly at the expense of too much noise
* Adding rake as a runtime dependency
* If the schema is already in the model file, it will be replaced into the same
location. If it didn't previously exist, it'll be placed according to the
"position", as before.
* Allow task loading from Rakefile for gems (plugin installation already
auto-detects).
* Add skip_on_db_migrate option as well for people that don't want it
* Fix options parsing to convert strings to proper booleans
* Add support for Fabrication fabricators
* Leave magic encoding comment intact
* Fix issue #14 - RuntimeError: Already memoized
* Count a model as 'annotated' if any of its tests/fixtures are annotated
* Support FactoryGirl
* Support :change migrations (Rails 3.1)
* Allow models with non-standard capitalization
* Widen type column so we can handle longtexts with chopping things off.
* Skip trying to get list of models from commandline when running via Rake (was
preventing the use of multiple rake tasks in one command if one of them was
db:migrate).
* Add ability to skip annotations for a model by adding
'# -*- SkipSchemaAnnotations' anywhere in the file.
* Don't show column limits for integer and boolean types.
* Add sorting for columns and indexes. (Helpful for out-of-order migration
execution. Use --sort if you want this.)
* Annotate unit tests in subfolders.
* Add generator to install rakefile that automatically annotates on db:migrate.
* Correct Gemfile to clarify which environments need which gems.
* Add an .rvmrc to facilitate clean development.
* Refactor out ActiveRecord monkey-patch to permit extending without
side-effects.
* Use ObjectSpace to locate models to facilitate handling of models with
non-standard capitalization.
Note that this still requires that the inflector be configured to understand
the special case.
* Shore up test cases a bit.
* Merge against many of the older branches on Github whose functionality is
already reflected to reduce confusion about what is and is not implemented
here.
* Accept String or Symbol for :position (et al) options.
* Add RDoc output formatting as an option.
* Add Markdown output formatting as an option.
* Add option to force annotation regeneration.
* Add new configuration option for controlling where info is placed in
fixtures/factories.
* Fix for models without tables.
* Fix gemspec generation now that Jeweler looks at Gemfile.
* Fix warning: `NOTE: Gem::Specification#default_executable= is deprecated with
no replacement. It will be removed on or after 2011-10-01.`
* Fix handling of files with no trailing newline when putting annotations at
the end of the file.
* Now works on tables with no primary key.
* --format=markdown option
* --trace option to help debug "Unable to annotate" errors
* "Table name" annotation (if table name is different from model name)
* "Human name" annotation (enabling translation to non-English locales)
* Fix JRuby ObjectSpace compatibility bug (https://github.com/ctran/annotate_models/pull/85)
* Fix FactoryGirl compatibility bug (https://github.com/ctran/annotate_models/pull/82)
== 2.4.2 2009-11-21
* Annotates (spec|test)/factories/<model>_factory.rb files
== 2.4.1 2009-11-20
* Annotates thoughtbot's factory_girl factories (test/factories/<model>_factory.rb)
* Move default annotation position back to top
== 2.4.0 2009-12-13
* Incorporated lots of patches from the Github community, including support for
Blueprints fixtures
* Several bug fixes
== 2.1 2009-10-18
* New options
* -R to require additional files before loading the models
* -i to show database indexes in annotations
* -e to exclude annotating tests or fixtures
* -m to include the migration version number in the annotation
* --model-dir to annotate model files stored a different place than app/models
* Ignore unknown macros ('acts_as_whatever')
== 2.0 2009-02-03
* Add annotate_models plugin fork additions
* Annotates Rspec and Test Unit models
* Annotates Object Daddy exemplars
* Annotates geometrical columns
* Add AnnotateRoutes rake task
* Up gem structure to newgem defaults
== 1.0.4 2008-09-04
* Only update modified models since last run, thanks to sant0sk1
== 1.0.3 2008-05-02
* Add misc changes from Dustin Sallings and Henrik N
* Remove trailing whitespace
* More intuitive info messages
* Update README file with update-to-date example
== 1.0.2 2008-03-22
* Add contributions from Michael Bumann (http://github.com/bumi)
* added an option "position" to choose to put the annotation,
* spec/fixtures now also get annotated
* added a task to remove the annotations
* these options can be specified from command line as -d and -p [before|after]
README.rdoc → README.md
== Annotate (aka AnnotateModels)
## Annotate (aka AnnotateModels)
{<img src="https://badge.fury.io/rb/annotate.svg" alt="Gem Version" />}[http://badge.fury.io/rb/annotate]
{<img src="https://img.shields.io/gem/dt/annotate.svg?style=flat" />}[https://rubygems.org/gems/annotate]
{<img src="https://travis-ci.org/ctran/annotate_models.svg?branch=develop" />}[https://travis-ci.org/ctran/annotate_models]
{<img src="https://github.com/ctran/annotate_models/workflows/CI/badge.svg" />}[https://github.com/ctran/annotate_models/actions?workflow=CI]
{<img src="https://coveralls.io/repos/ctran/annotate_models/badge.svg?branch=develop" />}[https://coveralls.io/r/ctran/annotate_models?branch=develop]
{<img src="https://codeclimate.com/github/ctran/annotate_models/badges/gpa.svg" />}[https://codeclimate.com/github/ctran/annotate_models]
{<img src="http://inch-ci.org/github/ctran/annotate_models.svg?branch=develop" alt="Inline docs" />}[http://inch-ci.org/github/ctran/annotate_models]
[![Gem Version](https://badge.fury.io/rb/annotate.svg)](http://badge.fury.io/rb/annotate)
[![Downloads count](https://img.shields.io/gem/dt/annotate.svg?style=flat)](https://rubygems.org/gems/annotate)
[![Build status](https://travis-ci.org/ctran/annotate_models.svg?branch=develop)](https://travis-ci.org/ctran/annotate_models)
[![CI Status](https://github.com/ctran/annotate_models/workflows/CI/badge.svg)](https://github.com/ctran/annotate_models/actions?workflow=CI)
[![Coveralls](https://coveralls.io/repos/ctran/annotate_models/badge.svg?branch=develop)](https://coveralls.io/r/ctran/annotate_models?branch=develop)
[![Maintenability](https://codeclimate.com/github/ctran/annotate_models/badges/gpa.svg)](https://codeclimate.com/github/ctran/annotate_models)
[![Inline docs](http://inch-ci.org/github/ctran/annotate_models.svg?branch=develop)](http://inch-ci.org/github/ctran/annotate_models)
Add a comment summarizing the current schema to the top or bottom of each of
your...
Add a comment summarizing the current schema to the top or bottom of each of your...
- ActiveRecord models
- Fixture files
......@@ -17,72 +16,85 @@ your...
- 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)
- Thoughtbot's factory_bot factories, i.e. the `(spec|test)/factories/<model>_factory.rb` files
- `routes.rb` file (for Rails projects)
The schema comment looks like this:
# == 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
```ruby
# == 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
. . .
```
It also annotates geometrical columns, `geom` type and `srid`,
when using `SpatialAdapter`, `PostgisAdapter` or `PostGISAdapter`:
```ruby
# == Schema Info
#
# Table name: trips
#
# local :geometry point, 4326
# path :geometry line_string, 4326
```
It also annotates geometrical columns, geom type and srid, when using
+SpatialAdapter+, +PostgisAdapter+ or +PostGISAdapter+:
Also, if you pass the `-r` option, it'll annotate `routes.rb` with the output of `rake routes`.
# == Schema Info
#
# Table name: trips
#
# local :geometry point, 4326
# path :geometry line_string, 4326
Also, if you pass the -r option, it'll annotate routes.rb with the output of
<code>rake routes</code>.
## Upgrading to 3.X and annotate models not working?
== Upgrading to 3.X and annotate models not working?
In versions 2.7.X the annotate gem defaulted to annotating models if no arguments were passed in. The annotate gem by default would not allow for routes and models to be annotated together. A
{change was added in #647}[link:https://github.com/ctran/annotate_models/pull/647]. You {can read more here}[https://github.com/ctran/annotate_models/issues/663].
In versions 2.7.X the annotate gem defaulted to annotating models if no arguments were passed in.
The annotate gem by default would not allow for routes and models to be annotated together.
A [change was added in #647](https:/github.com/ctran/annotate_models/pull/647).
You [can read more here](https://github.com/ctran/annotate_models/issues/663).
There are a few ways of fixing this.
If using CLI explicitly pass in models flag using +--models+
There are a few ways of fixing this:
- If using CLI explicitly pass in models flag using `--models`
OR
a) Running
rails g annotate:install
will overwrite your defaults with the annotating models option set to true.
a) Running `rails g annotate:install` will overwrite your defaults with the annotating `models` option set to `'true'`.
b) In +lib/tasks/auto_annotate_models.rake+ add the models key-value option:
b) In `lib/tasks/auto_annotate_models.rake` add the `models` key-value option:
```ruby
Annotate.set_defaults(
...
'models' => 'true',
...
```
== Install
## Install
Into Gemfile from rubygems.org:
group :development do
```ruby
group :development do
gem 'annotate'
end
end
```
Into Gemfile from Github:
group :development do
```ruby
group :development do
gem 'annotate', git: 'https://github.com/ctran/annotate_models.git'
end
end
```
Into environment gems from rubygems.org:
......@@ -95,12 +107,11 @@ Into environment gems from Github checkout:
rake build
gem install pkg/annotate-*.gem
## Usage
== Usage
(If you used the Gemfile install, prefix the below commands with `bundle exec`.)
(If you used the Gemfile install, prefix the below commands with <code>bundle exec</code>.)
=== Usage in Rails
### Usage in Rails
To annotate all your models, tests, fixtures, and factories:
......@@ -127,26 +138,28 @@ To remove routes.rb annotations:
annotate --routes --delete
To automatically annotate every time you run <code>db:migrate</code>, either run <code>rails g annotate:install</code> or add +Annotate.load_tasks+ to your `Rakefile`. See the {configuration in Rails}[link:README.rdoc#configuration-in-rails] section for more info.
To automatically annotate every time you run `db:migrate`,
either run `rails g annotate:install`
or add `Annotate.load_tasks` to your `Rakefile`.
=== Usage Outside of Rails
See the [configuration in Rails](#configuration-in-rails) section for more info.
Everything above applies, except that +--routes+ is not meaningful, and you will
probably need to explicitly set one or more +--require+ option(s), and/or one
or more +--model-dir+ options to inform annotate about the structure of your
project and help it bootstrap and load the relevant code.
### Usage Outside of Rails
Everything above applies, except that `--routes` is not meaningful,
and you will probably need to explicitly set one or more `--require` option(s), and/or one or more `--model-dir` options
to inform `annotate` about the structure of your project and help it bootstrap and load the relevant code.
== Configuration
## Configuration
If you want to always skip annotations on a particular model, add this string
anywhere in the file:
# -*- SkipSchemaAnnotations
=== Configuration in Rails
### Configuration in Rails
To generate a configuration file (in the form of a +.rake+ file), to set
To generate a configuration file (in the form of a `.rake` file), to set
default options:
rails g annotate:install
......@@ -154,7 +167,7 @@ default options:
Edit this file to control things like output format, where annotations are
added (top or bottom of file), and in which artifacts.
The generated rakefile +lib/tasks/auto_annotate_models.rake+ also contains
The generated rakefile `lib/tasks/auto_annotate_models.rake` also contains
`Annotate.load_tasks`. This adds a few rake tasks which duplicate command-line
functionality:
......@@ -163,24 +176,27 @@ functionality:
rake remove_annotation # Remove schema information from model and fixture files
By default, once you've generated a configuration file, annotate will be
executed whenever you run <code>rake db:migrate</code> (but only in development mode).
If you want to disable this behavior permanently, edit the +.rake+ file and
change:
executed whenever you run `rake db:migrate` (but only in development mode).
If you want to disable this behavior permanently,
edit the `.rake` file and change:
```ruby
'skip_on_db_migrate' => 'false',
```
To:
```ruby
'skip_on_db_migrate' => 'true',
```
If you want to run <code>rake db:migrate</code> as a one-off without running annotate,
If you want to run `rake db:migrate` as a one-off without running annotate,
you can do so with a simple environment variable, instead of editing the
+.rake+ file:
`.rake` file:
ANNOTATE_SKIP_ON_DB_MIGRATE=1 rake db:migrate
== Options
## Options
Usage: annotate [options] [model_file]*
--additional_file_patterns Additional file paths or globs to annotate, separated by commas (e.g. `/foo/bar/%model_name%/*.rb,/baz/%model_name%.rb`)
......@@ -236,82 +252,80 @@ you can do so with a simple environment variable, instead of editing the
--ignore-unknown-models don't display warnings for bad model files
--with-comment include database comments in model annotations
=== Option: +additional_file_patterns+
### Option: `additional_file_patterns`
CLI: +--additional_file_patterns+<br>
Ruby: +:additional_file_patterns+
CLI: `--additional_file_patterns`<br>
Ruby: `:additional_file_patterns`
Provide additional paths for the gem to annotate. These paths can include globs.
It is recommended to use absolute paths. Here are some examples:
Provide additional paths for the gem to annotate. These paths can include
globs. It is recommended to use absolute paths. Here are some examples:
* `/app/lib/decorates/%MODEL_NAME%/&ast;.rb`
* `/app/lib/forms/%PLURALIZED_MODEL_NAME%/&ast;&ast;/&ast;.rb`
* `/app/lib/forms/%TABLE_NAME%/&ast;.rb`
- <code>/app/lib/decorates/%MODEL_NAME%/&ast;.rb</code>
- <code>/app/lib/forms/%PLURALIZED_MODEL_NAME%/&ast;&ast;/&ast;.rb</code>
- <code>/app/lib/forms/%TABLE_NAME%/&ast;.rb</code>
The appropriate model will be inferred using the <code>%*%</code> syntax, annotating any matching files.
It works with existing filename resolutions (options for which can be found in the +resolve_filename+ method of
+annotate_models.rb+).
The appropriate model will be inferred using the `%*%` syntax, annotating any
matching files. It works with existing filename resolutions (options for which
can be found in the `resolve_filename` method of `annotate_models.rb`).
When using in a Rails config, you can use the following:
<code>File.join(Rails.application.root, 'app/lib/forms/%PLURALIZED_MODEL_NAME%/**/*.rb')</code>
`File.join(Rails.application.root,
'app/lib/forms/%PLURALIZED_MODEL_NAME%/***/**.rb')`
== Sorting
## Sorting
By default, columns will be sorted in database order (i.e. the order in which
migrations were run).
If you prefer to sort alphabetically so that the results of
annotation are consistent regardless of what order migrations are executed in,
use +--sort+.
If you prefer to sort alphabetically so that the results of annotation are
consistent regardless of what order migrations are executed in, use `--sort`.
== Markdown
## Markdown
The format produced is actually MultiMarkdown, making use of the syntax
extension for tables. It's recommended you use +kramdown+ as your parser if
you want to use this format. If you're using +yard+ to generate documentation,
specify a format of markdown with +kramdown+ as the provider by adding this to
your +.yardopts+ file:
extension for tables. It's recommended you use `kramdown` as your parser if
you want to use this format. If you're using `yard` to generate
documentation, specify a format of markdown with `kramdown` as the provider by
adding this to your `.yardopts` file:
--markup markdown
--markup-provider kramdown
Be sure to add this to your +Gemfile+ as well:
gem 'kramdown', :groups => [:development], :require => false
Be sure to add this to your `Gemfile` as well:
gem 'kramdown', groups => [:development], require => false
== WARNING
## WARNING
<b>Don't add text after an automatically-created comment block.</b> This tool
**Don't add text after an automatically-created comment block.** This tool
will blow away the initial/final comment block in your models if it looks like
it was previously added by this gem.
Be sure to check the changes that this tool makes! If you are using Git,
you may simply check your project's status after running +annotate+:
Be sure to check the changes that this tool makes! If you are using Git, you
may simply check your project's status after running `annotate`:
$ git status
If you are not using a VCS (like Git, Subversion or similar), please tread
extra carefully, and consider using one.
== Links
## Links
- 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
* 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
== License
## License
Released under the same license as Ruby. No Support. No Warranty.
== Authors
## Authors
{See AUTHORS.rdoc}[link:AUTHORS.rdoc].
[See AUTHORS.md](AUTHORS.md).
RELEASE.md 0 → 100644
## Prerequisite
- Install "git-flow" (`brew install git-flow`)
- Install "bump" gem (`gem install bump`)
## Perform a release
- `git flow release start <release>`
- Update the `CHANGELOG.md` file
- `bump current`
- `bump patch`
- `rm -rf dist`
- `rake spec`
- `rake gem`
- `git flow release finish <release>`
- `rake gem:publish`
RELEASE.rdoc deleted 100644 → 0
== Prerequisite
- Install "git-flow" (brew install git-flow)
- Install "bump" gem (gem install bump)
== Perform a release
- git flow release start <release>
- Update the CHANGELOG.rdoc file
- bump current
- bump patch
- rm -rf dist
- rake spec
- rake gem
- git flow release finish <release>
- rake gem:publish
Rakefile
......@@ -60,7 +60,7 @@ namespace :gem do
end
gem.executables = `git ls-files -- bin/*`.split("\n").map { |f| File.basename(f) }
gem.extra_rdoc_files = ['README.rdoc', 'CHANGELOG.rdoc', 'TODO.rdoc']
gem.extra_rdoc_files = ['README.md', 'CHANGELOG.md', 'TODO.md']
gem.files = `git ls-files -- .`.split("\n").reject do |fn|
fn =~ /^Gemfile.*/ ||
......
TODO.rdoc → TODO.md
== TODO
## TODO
- clean up history
- change default position back to "top" for all annotations
- change 'exclude' to 'only' (double negatives are not unconfusing)
== TODO (proposed)
## TODO (proposed)
- push two identical gems, named 'annotate' and 'annotate_models'
- supply two binaries, named 'annotate' and 'annotate_models', since there's already a unix tool named 'annotate'
......
annotate.gemspec
......@@ -13,8 +13,8 @@ Gem::Specification.new do |s|
s.description = 'Annotates Rails/ActiveRecord Models, routes, fixtures, and others based on the database schema.'
s.email = ['alex@stinky.com', 'cuong.tran@gmail.com', 'x@nofxx.com', 'turadg@aleahmad.net', 'jon@cloudability.com']
s.executables = ['annotate']
s.extra_rdoc_files = ['README.rdoc', 'CHANGELOG.rdoc', 'TODO.rdoc']
s.files = `git ls-files -z LICENSE.txt *.rdoc *.gemspec bin lib`.split("\x0")
s.extra_rdoc_files = ['README.md', 'CHANGELOG.md', 'TODO.md']
s.files = `git ls-files -z LICENSE.txt *.md *.gemspec bin lib`.split("\x0")
s.homepage = 'http://github.com/ctran/annotate_models'
s.licenses = ['Ruby']
s.require_paths = ['lib']
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment