Start the README refactor and add a section for callbacks (#552)

Start the README refactor and add a section for callbacks

Closes #442

Reorganize the README to explicitly have a section dedicated to usage of
activerecord-import, similar to how the wiki is currently laid out.

Add a note that the wiki is not to be added to going forward.

Migrate the callbacks wiki article to the README, plus add the example
from #442 to add an example of how callbacks and validations can
interact in a different fashion.

README.markdown

@@ -21,11 +21,53 @@ and then the reviews:
 That would be about 4M SQL insert statements vs 3, which results in vastly improved performance. In our case, it converted
 an 18 hour batch process to <2 hrs.
 
-### More Information : Usage and Examples in Wiki
+## Table of Contents
 
-For more information on activerecord-import please see its wiki: https://github.com/zdennis/activerecord-import/wiki
+* [Callbacks](#callbacks)
+* [Additional Adapters](#additional-adapters)
+* [Load Path Setup](#load-path-setup)
+* [More Information](#more-information)
+
+### Callbacks
+
+ActiveRecord callbacks related to [creating](http://guides.rubyonrails.org/active_record_callbacks.html#creating-an-object), [updating](http://guides.rubyonrails.org/active_record_callbacks.html#updating-an-object), or [destroying](http://guides.rubyonrails.org/active_record_callbacks.html#destroying-an-object) records (other than `before_validation` and `after_validation`) will NOT be called when calling the import method. This is because it is mass importing rows of data and doesn't necessarily have access to in-memory ActiveRecord objects.
+
+If you do have a collection of in-memory ActiveRecord objects you can do something like this:
+
+```
+books.each do |book|
+  book.run_callbacks(:save) { false }
+  book.run_callbacks(:create) { false }
+end
+Book.import(books)
+```
+
+This will run before_create and before_save callbacks on each item. The `false` argument is needed to prevent after_save being run, which wouldn't make sense prior to bulk import. Something to note in this example is that the before_create and before_save callbacks will run before the validation callbacks.
+
+If that is an issue, another possible approach is to loop through your models first to do validations and then only run callbacks on and import the valid models.
+
+```
+valid_books = []
+invalid_books = []
+
+books.each do |book|
+  if book.valid?
+    valid_books << book
+  else
+    invalid_books << book
+  end
+end
+
+valid_books.each do |book|
+  book.run_callbacks(:save) { false }
+  book.run_callbacks(:create) { false }
+end
+
+Book.import valid_books, validate: false
+```
+
+### Additional Adapters
 
-## Additional Adapters
 Additional adapters can be provided by gems external to activerecord-import by providing an adapter that matches the naming convention setup by activerecord-import (and subsequently activerecord) for dynamically loading adapters.  This involves also providing a folder on the load path that follows the activerecord-import naming convention to allow activerecord-import to dynamically load the file.
 
 When `ActiveRecord::Import.require_adapter("fake_name")` is called the require will be:
@@ -63,6 +105,12 @@ activerecord-import-fake_name/
 
 When rubygems pushes the `lib` folder onto the load path a `require` will now find `activerecord-import/active_record/adapters/fake_name_adapter` as it runs through the lookup process for a ruby file under that path in `$LOAD_PATH`
 
+### More Information
+
+For more information on activerecord-import please see its wiki: https://github.com/zdennis/activerecord-import/wiki
+
+To document new information, please add to the README instead of the wiki. See https://github.com/zdennis/activerecord-import/issues/397 for discussion.
+
 # License
 
 This is licensed under the ruby license.