Split the docs in the READM into multiple files so that we can expand on them.

This is the start of a new push for beter / deeper documentation. Now
that we have them split out, we can revamp the README and the website.

Author: gregbell

.yardopts

@@ -0,0 +1,8 @@
+lib/**/*.rb 
+--protected
+--no-private
+--asset docs/images:images
+-
+README.rdoc 
+CHANGELOG.rdoc
+docs/**/*.md

docs/1-general-configuration.md

@@ -0,0 +1,52 @@
+# General Configuration
+
+## Admin Users
+
+By default Active Admin will include Devise and create a new model called
+AdminUser. If you would like to use another name, you can pass it in to the
+installer through the user option:
+
+    $> rails generate active_admin:install UserClassName
+
+If you don't want the generator to create any user classes:
+
+    $> rails generate active_admin:install --skip-users
+
+## Authentication
+
+Active Admin requires two settings to authenticate and use the current user
+within your application. Both are set in
+<tt>config/initializers/active_admin.rb</tt>. By default they are setup for use
+with Devise and a model named AdminUser. If you chose a different model name,
+you will need to update these settings.
+
+Set the method that controllers should call to authenticate the current user
+with:
+
+    # config/initializers/active_admin.rb
+    config.authentication_method = :authenticate_admin_user!
+
+Set the method to call within the view to access the current admin user
+
+    # config/initializers/active_admin.rb
+    config.current_user_method = :current_admin_user
+
+Both of these settings can be set to false to turn off authentication.
+
+    # Turn off authentication all together
+    config.authentication_method = false
+    config.current_user_method   = false
+
+## Site Title
+
+You can update the title used for the site in the initializer also. By default
+it is set to the name of your Rails.application class name.
+
+    # config/initializers/active_admin.rb
+    config.site_title = "My Admin Site"
+
+## Internationalization (I18n)
+
+To internationalize Active Admin or to change default strings, you can copy
+lib/active_admin/locales/en.yml to your application config/locales directory and
+change its content. You can contribute to the project with your translations to!

docs/2-resource-customization.md

@@ -0,0 +1,35 @@
+# Customize The Resource
+
+## Rename the Resource
+
+By default, any references to the resource (menu, routes, buttons, etc) in the
+interface will use the name of the class. You can rename the resource by using
+the <tt>:as</tt> option.
+
+    ActiveAdmin.register Post, :as => "Article"
+
+The resource will then be available as /admin/articles
+
+## Customize the Navigation
+
+The resource will be displayed in the global navigation by default.
+
+To disable the resource from being displayed in the global navigation:
+
+    ActiveAdmin.register Post do
+      menu false
+    end
+
+To change the name of the label in the menu:
+
+    ActiveAdmin.register Post do
+      menu :label => "My Posts"
+    end
+
+To add the menu as a child of another menu:
+
+    ActiveAdmin.register Post do
+      menu :parent => "Blog"
+    end
+
+This will create the menu item if it doesn't exist yet.

docs/3-index-pages.md

@@ -0,0 +1,164 @@
+# Customizing the Index Page
+
+Filtering and listing resources is one of the most important tasks for
+administering a web application. Active Admin provides many different tools for
+you to build a compelling interface into your data for the admin staff.
+
+Built in, Active Admin has the following index renderers:
+
+* *Table*: A table drawn with each row being a resource
+* *Grid*: A set of rows and columns each cell being a resource
+* *Blocks*: A set of rows (not tabular) each row being a resource
+* *Blog*: A title and body content, similar to a blog index
+
+All index pages also support scopes, filters, pagination, action items, and
+sidebar sections.
+
+## Index as a Table
+
+By default, the index page is a table with each of the models content columns and links to
+show, edit and delete the object. There are many ways to customize what gets
+displayed.
+
+### Defining Columns
+
+To display an attribute or a method on a resource, simply pass a symbol into the
+column method:
+
+    index do
+      column :title
+    end
+
+If the default title does not work for you, pass it as the first argument:
+
+    index do
+      column "My Custom Title", :title
+    end
+
+Sometimes calling methods just isn't enough and you need to write some view
+specific code. For example, say we wanted a colum called Title which holds a
+link to the posts admin screen.
+
+The column method accepts a block as an argument which will then be rendered
+within the context of the view for each of the objects in the collection.
+
+    index do
+      column "Title" do |post|
+        link_to post.title, admin_post_path(post)
+      end
+    end
+
+The block gets called once for each resource in the collection. The resource gets passed into
+the block as an argument.
+
+
+### Sorting
+
+When a column is generated from an Active Record attribute, the table is
+sortable by default. If you are creating a custom column, you may need to give
+Active Admin a hint for how to sort the table.
+
+If a column is defined using a block, you must pass the key to turn on sorting. The key
+is the attribute which gets used to sort objects using Active Record.
+
+    index do
+      column "Title", :sortable => :title do |post|
+        link_to post.title, admin_post_path(post)
+      end
+    end
+
+You can turn off sorting on any column by passing false:
+
+    index do
+      column :title, :sortable => false
+    end
+
+### Showing and Hiding Columns
+
+The entire index block is rendered within the context of the view, so you can
+easily do things that show or hide columns based on the current context.
+
+For example, if you were using CanCan:
+
+    index do
+      column :title, :sortable => false
+      if can? :manage, Post
+        column :some_secret_data
+      end
+    end
+
+## Index as a Grid
+
+Sometimes you want to display the index screen for a set of resources as a grid
+(possibly a grid of thumbnail images). To do so, use the :grid option for the
+index block.
+
+    index :as => :grid do |product|
+      link_to(image_tag(product.image_path), admin_products_path(product))
+    end
+
+The block is rendered within a cell in the grid once for each resource in the
+collection. The resource is passed into the block for you to use in the view.
+
+You can customize the number of colums that are rendered using the columns
+option:
+
+    index :as => :grid, :columns => 5 do |product|
+      link_to(image_tag(product.image_path), admin_products_path(product))
+    end
+
+
+## Index as a Block
+
+If you want to fully customize the display of your resources on the index
+screen, Index as a Block allows you to render a block of content for each
+resource.
+
+    index :as => :block do |product|
+      div :for => product do
+        h2 auto_link(product.title)
+        div do
+          simple_format product.description
+        end
+      end
+    end
+
+## Index Filters
+
+By default the index screen includes a "Filters" sidebar on the right hand side
+with a filter for each attribute of the registered model. You can customize the
+filters that are displayed as well as the type of widgets they use.
+
+To display a filter for an attribute, use the filter method
+
+    ActiveAdmin.register Post do
+      filter :title
+    end
+
+Out of the box, Active Admin supports the following filter types:
+
+* *:string* - A search field
+* *:date_range* - A start and end date field with calendar inputs
+* *:numeric* - A drop down for selecting "Equal To", "Greater Than" or "Less
+  Than" and an input for a value.
+* *:select* - A drop down which filters based on a selected item in a collection
+  or all.
+* *:check_boxes* - A list of check boxes users can turn on and off to filter
+
+By default, Active Admin will pick the most relevant filter based on the
+attribute type. You can force the type by passing the :as option.
+
+    filter :author, :as => :check_boxes
+
+The :check_boxes and :select types accept options for the collection. By default
+it attempts to create a collection based on an association. But you can pass in
+the collection as a proc to be called at render time.
+
+    # Will call available
+    filter :author, :as => :check_boxes, :collection => proc { Author.all }
+
+You can change the filter label by passing a label option:
+
+    filter :author, :label => 'Author'
+
+By default, Active Admin will try to use ActiveModel I18n to determine the label.

docs/4-csv-format.md

@@ -0,0 +1,8 @@
+# Customizing the CSV format
+
+Customizing the CSV format is as simple as customizing the index page.
+
+  csv do
+    column :name
+    column("Author") { |post| post.author.full_name }
+  end

docs/5-forms.md

@@ -0,0 +1,39 @@
+# Customizing the Form
+
+Active Admin gives complete control over the output of the form by creating a thin DSL on top of
+the fabulous DSL created by Formtastic (http://github.com/justinfrench/formtastic).
+
+    ActiveAdmin.register Post do
+
+      form do |f|
+        f.inputs "Details" do
+          f.input :title
+          f.input :published_at, :label => "Publish Post At"
+          f.input :category
+        end
+        f.inputs "Content" do
+          f.input :body
+        end
+        f.buttons
+      end
+
+    end
+
+Please view the documentation for Formtastic to see all the wonderful things you can do:
+http://github.com/justinfrench/formtastic
+
+If you require a more custom form than can be provided through the DSL, you can pass
+a partial in to render the form yourself.
+
+For example:
+
+    ActiveAdmin.register Post do
+      form :partial => "form"
+    end
+
+Then implement app/views/admin/posts/_form.html.erb:
+
+    <%= semantic_form_for [:admin, @post] do |f| %>
+      <%= f.inputs :title, :body %>
+      <%= f.buttons :commit %>
+    <% end %>

docs/6-show-screens.md

@@ -0,0 +1,22 @@
+# Customizing the Show Screen
+
+Customizing the show screen is as simple as implementing the show block:
+
+    ActiveAdmin.register Post do
+      show do
+        h3 post.title
+        div do
+          simple_format post.body
+        end
+      end
+    end
+
+The show block is rendered within the context of the view and uses the Arbre HTML DSL. You
+can also render a partial at any point.
+
+    ActiveAdmin.register Post do
+      show do
+        # renders app/views/admin/posts/_some_partial.html.erb
+        render "some_partial"
+      end
+    end

docs/7-sidebars.md

@@ -0,0 +1,35 @@
+# Sidebar Sections
+
+To add a sidebar section to all the screen within a section, use the sidebar method:
+
+    sidebar :help do
+      "Need help? Email us at [email protected]"
+    end
+
+This will generate a sidebar section on each screen of the resource. With the block as
+the contents of the section. The first argument is the section title.
+
+You can also use Arbre syntax to define the content.
+
+    sidebar :help do
+      ul do
+        li "Second List First Item"
+        li "Second List Second Item"
+      end
+    end
+
+Sidebar sections can be rendered on a specific action by using the :only or :except
+options.
+
+    sidebar :help, :only => :index do
+      "Need help? Email us at [email protected]"
+    end
+
+If you only pass a symbol, Active Admin will attempt to locate a partial to render.
+
+    # Will render app/views/admin/posts/_help_sidebar.html.erb
+    sidebar :help
+
+Or you can pass your own custom partial to render.
+
+    sidebar :help, :partial => "custom_help_partial"

docs/8-custom-actions.md

@@ -0,0 +1,19 @@
+# Add collection and member actions
+
+## Add Custom Collection Action
+
+To add a collection action, use the collection_action method:
+
+  collection_action :import_csv do
+    # do csv import
+    redirect_to :action => :index, :notice => "CSV imported successfully!"
+  end
+
+## Add Custom Member Action
+
+To add a member action, use the member_action method:
+
+  member_action :lock, :method => :post do
+    resource.lock!
+    redirect_to :action => :show, :notice => "Locked!"
+  end