Move documentation into main repository

CHANGELOG.md

@@ -28,6 +28,7 @@
   generated `SHOW_PAGE_ATTRIBUTES` array elements.
 * [#297] [I18n] Add Italian translations
 * [#307] [I18n] Fix German grammatical errors
+* [#363] [DOC] Move documentation into main repository, at the root URL
 
 ### 0.1.2 (December 09, 2015)
 

Gemfile

@@ -6,7 +6,9 @@ gemspec
 
 gem "delayed_job_active_record"
 gem "high_voltage"
+gem "markdown-rails"
 gem "pg"
+gem "redcarpet"
 gem "unicorn"
 
 group :development do

Gemfile.lock

@@ -156,6 +156,9 @@ GEM
       nokogiri (>= 1.5.9)
     mail (2.6.3)
       mime-types (>= 1.16, < 3)
+    markdown-rails (0.2.1)
+      rails
+      rdiscount (>= 1.6.8, < 2.0)
     method_source (0.8.2)
     mime-types (2.6.2)
     mini_portile2 (2.0.0)
@@ -218,6 +221,8 @@ GEM
       thor (>= 0.18.1, < 2.0)
     raindrops (0.15.0)
     rake (10.4.2)
+    rdiscount (1.6.8)
+    redcarpet (3.3.3)
     rspec (3.1.0)
       rspec-core (~> 3.1.0)
       rspec-expectations (~> 3.1.0)
@@ -310,12 +315,14 @@ DEPENDENCIES
   high_voltage
   i18n-tasks
   launchy
+  markdown-rails
   percy-capybara
   pg
   poltergeist
   pry-rails
   rack-timeout
   rails_stdout_logging
+  redcarpet
   rspec-rails (~> 3.1.0)
   shoulda-matchers (~> 2.8.0)
   timecop

README.md

@@ -4,22 +4,27 @@
 [![Gem Version](https://badge.fury.io/rb/administrate.svg)](https://badge.fury.io/rb/administrate)
 [![Code Climate](https://codeclimate.com/github/thoughtbot/administrate/badges/gpa.svg)](https://codeclimate.com/github/thoughtbot/administrate)
 
-A Rails engine that helps you put together a super-flexible admin dashboard.
+A framework for creating flexible, powerful admin dashboards in Rails.
 [Try the demo][demo].
 
 > Note: Administrate is still pre-1.0,
 > and there may be occasional breaking changes to the API.
 
 ![administrate](https://images.thoughtbot.com/announcing-administrate/DdP2CQfnSE23PI8AAnDc_Administrate.png)
 
-## Guiding Principles
+## What Is Administrate?
 
-Administrate is heavily inspired by projects
-like [Rails Admin] and [ActiveAdmin],
+Administrate is a library for Rails apps
+that automatically generates admin dashboards.
+Administrate's admin dashboards give non-technical users clean interfaces
+that allow them to create, edit, search, and delete records
+for any model in the application.
+
+Administrate solves the same problem as [Rails Admin] and [ActiveAdmin],
 but aims to provide a better user experience for site admins,
 and to be easier for developers to customize.
 
-To do that, Administrate follows a few simple rules:
+To accomplish these goals, Administrate follows a few guiding principles:
 
 - No DSLs (domain-specific languages)
 - Support the simplest use cases, and let the user override defaults with

app/assets/stylesheets/docs.scss

@@ -0,0 +1,92 @@
+$blue: #53adc6;
+$red: #cf726e;
+$green: #5bc89e;
+$white: #f0f0f0;
+
+$code-black: #202020;
+$code-white: #e0e0dc;
+$code-green: #b0bf82;
+$code-blue: #8fbdcc;
+$code-yellow: #f8d29d;
+$code-red: #b95c56;
+
+html,
+body {
+  font-family: 'Lato', serif;
+  font-size: 18px;
+  line-height: 1.62em;
+  margin: 0;
+}
+
+img {
+  max-width: 100%;
+}
+
+h1,
+h2,
+h3 {
+  font-family: 'Fjalla One', sans-serif;
+  margin-top: 2em;
+}
+
+a {
+  color: $blue;
+  text-decoration: none;
+}
+
+.content {
+  margin-bottom: 2em;
+  margin-left: auto;
+  margin-right: auto;
+  margin-top: 2em;
+  width: 60em;
+
+  .sidebar {
+    float: left;
+    width: 20em;
+
+    &-links {
+      list-style: none;
+      padding-left: 0;
+    }
+  }
+
+  .main {
+    float: right;
+    width: 40em;
+  }
+}
+
+.flash-wrapper {
+  background-color: $red;
+  color: $white;
+  padding: 1em;
+
+  .flash {
+    margin-left: auto;
+    margin-right: auto;
+    width: 40em;
+  }
+}
+
+code {
+  font-family: "Source Code Pro";
+  font-size: 0.8rem;
+  padding: 0.4em 0.2em 0;
+
+  &.hljs {
+    background-color: $code-black;
+    color: $code-white;
+    padding-left: 1rem;
+
+    .hljs-string { color: $code-green; }
+    .hljs-constant { color: $code-blue; }
+    .hljs-symbol { color: $code-red; }
+    .hljs-keyword { color: $code-yellow; }
+
+    .hljs-title,
+    .hljs-parent { color: $code-blue; }
+
+    .hljs-tag { color: $code-yellow; }
+  }
+}

app/controllers/docs_controller.rb

@@ -0,0 +1,9 @@
+class DocsController < ApplicationController
+  def index
+    render file: "README"
+  end
+
+  def show
+    render file: "docs/#{params[:page]}"
+  end
+end

app/views/layouts/docs.html.erb

@@ -0,0 +1,39 @@
+<html>
+<head>
+  <%= stylesheet_link_tag "docs", media: "all" %>
+  <link href='//fonts.googleapis.com/css?family=Lato|Source+Code+Pro|Fjalla+One' rel='stylesheet' type='text/css'>
+  <link rel="stylesheet" href="//cdnjs.cloudflare.com/ajax/libs/highlight.js/8.4/styles/default.min.css">
+</head>
+
+<body>
+  <div class="content">
+    <div class="sidebar">
+      <h1>Administrate</h1>
+
+      <ul class="sidebar-links">
+        <li><a href="/">Home</a></li>
+        <li><a href="https://github.com/thoughtbot/administrate/issues/new">Feedback</a></li>
+      </ul>
+
+      <h3>Documentation</h3>
+
+      <ul class="sidebar-links">
+        <li><a href="/">README</a></li>
+        <li><a href="/getting_started">Getting Started</a></li>
+        <li><a href="/customizing_dashboards">Customizing Dashboards</a></li>
+        <li><a href="/customizing_page_views">Customizing Page Views</a></li>
+        <li><a href="/customizing_attribute_partials">Customizing Attribute Partials</a></li>
+        <li><a href="/adding_custom_field_types">Adding Custom Field Types</a></li>
+        <li><a href="/customizing_controller_actions">Customizing Controller Actions</a></li>
+      </ul>
+    </div>
+
+    <div class="main">
+      <%= yield %>
+    </div>
+  </div>
+
+  <script src="//cdnjs.cloudflare.com/ajax/libs/highlight.js/8.4/highlight.min.js"></script>
+  <script>hljs.initHighlightingOnLoad();</script>
+</body>
+</html>

docs/adding_custom_field_types.md

@@ -0,0 +1,59 @@
+# Adding Custom Field Types
+
+If your application deals with a nonstandard data type,
+you can create an `Administrate::Field` object to help display
+the custom data type across the dashboard.
+
+`Administrate::Field` objects consist of two parts:
+a Ruby class and associated views.
+
+For example, let's create a `Field` that displays [Gravatars] based on an email.
+
+[Gravatars]: https://gravatar.com/
+
+First, we'll run a generator to set us up with the files we need:
+
+```bash
+rails generate administrate:field gravatar
+```
+
+This creates a few files:
+
+- `app/fields/gravatar_field.rb`
+- `app/views/fields/gravatar_field/_show.html.erb`
+- `app/views/fields/gravatar_field/_index.html.erb`
+- `app/views/fields/gravatar_field/_form.html.erb`
+
+We can edit the `app/fields/gravatar_field.rb` to add some custom logic:
+
+```ruby
+# app/fields/gravatar_field.rb
+require 'digest/md5'
+
+class GravatarField < Administrate::Field::Base
+  def gravatar_url
+    email_address = data.downcase
+    hash = Digest::MD5.hexdigest(email_address)
+    "http://www.gravatar.com/avatar/#{hash}"
+  end
+end
+```
+
+Next, we can customize the partials to display data how we'd like.
+Open up the `app/views/fields/gravatar_field/_show.html.erb` partial.
+By default, it looks like:
+
+```eruby
+<%= field.data %>
+```
+
+Since we want to display an image, we can change it to:
+
+```eruby
+<%= image_tag field.gravatar_url %>
+```
+
+You can customize the other generated partials in the same way
+for custom behavior on the index and form pages.
+
+[Customizing Attribute Partials]: /customizing_attribute_partials

docs/customizing_attribute_partials.md

@@ -0,0 +1,34 @@
+# Customizing attribute partials
+
+Occasionally you might want to change how specific types of attributes appear
+across all dashboards.
+For example, you might want all `Number` values to round to three decimal points.
+
+To get started, run the appropriate rails generator:
+
+```bash
+rails generate administrate:views:field number
+```
+
+This will generate three files:
+
+- `app/view/fields/form/_number.html.erb`
+- `app/view/fields/index/_number.html.erb`
+- `app/view/fields/show/_number.html.erb`
+
+The generated templates will have documentation
+describing which variables are in scope.
+The rendering part of the partial will look like:
+
+```eruby
+<%= field.data %>
+```
+
+Changing numbers to display to three decimal places might look like this:
+
+```eruby
+<%= field.data.round(3) %>
+```
+
+If you only want to change how an attribute appears
+on a single page (e.g. `index`), you may delete the unnecessary templates.

docs/customizing_controller_actions.md

@@ -0,0 +1,32 @@
+# Customizing controller actions
+
+When you install Administrate into your app,
+we generate empty controllers for each of your resources.
+If you want to create more complex application behavior for a dashboard,
+simply overwrite controller actions.
+
+The generated controller will look something like:
+
+```ruby
+# app/controllers/admin/foos_controller.rb
+
+class Admin::FoosController < Admin::ApplicationController
+
+  # Overwrite any of the RESTful controller actions to implement custom behavior
+  # For example, you may want to send an email after a foo is updated.
+  #
+  # def update
+  #   foo = Foo.find(params[:id])
+  #   foo.update(params[:foo])
+  #   send_foo_updated_email
+  # end
+
+  # Override this method to specify custom lookup behavior.
+  # This will be used to set the resource for the `show`, `edit`, and `update`
+  # actions.
+  #
+  # def find_resource(param)
+  #   Foo.find_by!(slug: param)
+  # end
+end
+```