Convert documentation files to Markdown (#697)

.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

+## 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

-== 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

+## 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

-== 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']