encapsulates API generation in Rails::API::Task

.gitignore

@@ -20,4 +20,3 @@ pkg
 /railties/doc
 /railties/tmp
 /guides/output
-/RDOC_MAIN.rdoc

RDOC_MAIN.rdoc

@@ -0,0 +1,73 @@
+== Welcome to \Rails
+
+\Rails is a web-application framework that includes everything needed to create
+database-backed web applications according to the {Model-View-Controller (MVC)}[http://en.wikipedia.org/wiki/Model%E2%80%93view%E2%80%93controller] pattern.
+
+Understanding the MVC pattern is key to understanding \Rails. MVC divides your application
+into three layers, each with a specific responsibility.
+
+The View layer is composed of "templates" that are responsible for providing
+appropriate representations of your application's resources. Templates
+can come in a variety of formats, but most view templates are \HTML with embedded Ruby
+code (.erb files).
+
+The Model layer represents your domain model (such as Account, Product, Person, Post)
+and encapsulates the business logic that is specific to your application. In \Rails,
+database-backed model classes are derived from ActiveRecord::Base. Active Record allows
+you to present the data from database rows as objects and embellish these data objects
+with business logic methods. Although most \Rails models are backed by a database, models
+can also be ordinary Ruby classes, or Ruby classes that implement a set of interfaces as
+provided by the ActiveModel module. You can read more about Active Record in its
+{README}[link:/activerecord/README.rdoc].
+
+The Controller layer is responsible for handling incoming HTTP requests and providing a
+suitable response. Usually this means returning \HTML, but \Rails controllers can also
+generate XML, JSON, PDFs, mobile-specific views, and more. Controllers manipulate models
+and render view templates in order to generate the appropriate HTTP response.
+
+In \Rails, the Controller and View layers are handled together by Action Pack.
+These two layers are bundled in a single package due to their heavy interdependence.
+This is unlike the relationship between Active Record and Action Pack, which are
+independent. Each of these packages can be used independently outside of \Rails. You
+can read more about Action Pack in its {README}[link:/actionpack/README.rdoc].
+
+== Getting Started
+
+1. Install \Rails at the command prompt if you haven't yet:
+
+    gem install rails
+
+2. At the command prompt, create a new \Rails application:
+
+    rails new myapp
+
+   where "myapp" is the application name.
+
+3. Change directory to +myapp+ and start the web server:
+
+    cd myapp; rails server
+
+   Run with <tt>--help</tt> or <tt>-h</tt> for options.
+
+4. Go to http://localhost:3000 and you'll see:
+
+    "Welcome aboard: You're riding Ruby on Rails!"
+
+5. Follow the guidelines to start developing your application. You may find the following resources handy:
+
+* The README file created within your application.
+* {Getting Started with \Rails}[http://guides.rubyonrails.org/getting_started.html].
+* {Ruby on \Rails Tutorial}[http://ruby.railstutorial.org/ruby-on-rails-tutorial-book].
+* {Ruby on \Rails Guides}[http://guides.rubyonrails.org].
+* {The API Documentation}[http://api.rubyonrails.org].
+
+== Contributing
+
+We encourage you to contribute to Ruby on \Rails! Please check out the {Contributing to Rails
+guide}[http://edgeguides.rubyonrails.org/contributing_to_ruby_on_rails.html] for guidelines about how
+to proceed. {Join us}[http://contributors.rubyonrails.org]!
+
+
+== License
+
+Ruby on \Rails is released under the {MIT License}[http://www.opensource.org/licenses/MIT].

Rakefile

@@ -1,9 +1,9 @@
-require 'rdoc/task'
 require 'sdoc'
 require 'net/http'
 
 $:.unshift File.expand_path('..', __FILE__)
 require "tasks/release"
+require 'railties/lib/rails/api/task'
 
 desc "Build gem files for all projects"
 task :build => "all:build"
@@ -47,88 +47,7 @@ task :install => :gem do
 end
 
 desc "Generate documentation for the Rails framework"
-RDoc::Task.new do |rdoc|
-  RDOC_MAIN = 'RDOC_MAIN.rdoc'
-
-  # This is a hack.
-  #
-  # Backslashes are needed to prevent RDoc from autolinking "Rails" to the
-  # documentation of the Rails module. On the other hand, as of this
-  # writing README.rdoc is displayed in the front page of the project in
-  # GitHub, where backslashes are shown and look weird.
-  #
-  # The temporary solution is to have a README.rdoc without backslashes for
-  # GitHub, and gsub it to generate the main page of the API.
-  #
-  # Also, relative links in GitHub have to point to blobs, whereas in the API
-  # they need to point to files.
-  #
-  # The idea for the future is to have totally different files, since the
-  # API is no longer a generic entry point to Rails and deserves a
-  # dedicated main page specifically thought as an API entry point.
-  rdoc.before_running_rdoc do
-    rdoc_main = File.read('README.rdoc')
-
-    # The ^(?=\S) assertion prevents code blocks from being processed,
-    # since no autolinking happens there and RDoc displays the backslash
-    # otherwise.
-    rdoc_main.gsub!(/^(?=\S).*?\b(?=Rails)\b/) { "#$&\\" }
-    rdoc_main.gsub!(%r{link:/rails/rails/blob/master/(\w+)/README\.rdoc}, "link:files/\\1/README_rdoc.html")
-
-    # Remove Travis and Gemnasium status images from API pages. Only the GitHub
-    # README page gets these images. Travis's HTTPS build image is used to
-    # avoid GitHub caching: http://about.travis-ci.org/docs/user/status-images
-    rdoc_main.gsub!(/^== Code Status(\n(?!==).*)*/, '')
-
-    File.open(RDOC_MAIN, 'w') do |f|
-      f.write(rdoc_main)
-    end
-
-    rdoc.rdoc_files.include(RDOC_MAIN)
-  end
-
-  rdoc.rdoc_dir = 'doc/rdoc'
-  rdoc.title    = "Ruby on Rails API"
-
-  rdoc.options << '-f' << 'sdoc'
-  rdoc.options << '-T' << 'rails'
-  rdoc.options << '-e' << 'UTF-8'
-  rdoc.options << '-g' # SDoc flag, link methods to GitHub
-  rdoc.options << '-m' << RDOC_MAIN
-
-  rdoc.rdoc_files.include('railties/CHANGELOG.md')
-  rdoc.rdoc_files.include('railties/MIT-LICENSE')
-  rdoc.rdoc_files.include('railties/README.rdoc')
-  rdoc.rdoc_files.include('railties/lib/**/*.rb')
-  rdoc.rdoc_files.exclude('railties/lib/rails/generators/**/templates/**/*.rb')
-
-  rdoc.rdoc_files.include('activerecord/README.rdoc')
-  rdoc.rdoc_files.include('activerecord/CHANGELOG.md')
-  rdoc.rdoc_files.include('activerecord/lib/active_record/**/*.rb')
-  rdoc.rdoc_files.exclude('activerecord/lib/active_record/vendor/*')
-
-  rdoc.rdoc_files.include('actionpack/README.rdoc')
-  rdoc.rdoc_files.include('actionpack/CHANGELOG.md')
-  rdoc.rdoc_files.include('actionpack/lib/abstract_controller/**/*.rb')
-  rdoc.rdoc_files.include('actionpack/lib/action_controller/**/*.rb')
-  rdoc.rdoc_files.include('actionpack/lib/action_dispatch/**/*.rb')
-  rdoc.rdoc_files.include('actionpack/lib/action_view/**/*.rb')
-  rdoc.rdoc_files.exclude('actionpack/lib/action_controller/vendor/*')
-
-  rdoc.rdoc_files.include('actionmailer/README.rdoc')
-  rdoc.rdoc_files.include('actionmailer/CHANGELOG.md')
-  rdoc.rdoc_files.include('actionmailer/lib/action_mailer/**/*.rb')
-  rdoc.rdoc_files.exclude('actionmailer/lib/action_mailer/vendor/*')
-
-  rdoc.rdoc_files.include('activesupport/README.rdoc')
-  rdoc.rdoc_files.include('activesupport/CHANGELOG.md')
-  rdoc.rdoc_files.include('activesupport/lib/active_support/**/*.rb')
-  rdoc.rdoc_files.exclude('activesupport/lib/active_support/vendor/*')
-
-  rdoc.rdoc_files.include('activemodel/README.rdoc')
-  rdoc.rdoc_files.include('activemodel/CHANGELOG.md')
-  rdoc.rdoc_files.include('activemodel/lib/active_model/**/*.rb')
-end
+Rails::API::Task.new('rdoc')
 
 desc 'Bump all versions to match version.rb'
 task :update_versions do

railties/lib/rails/api/task.rb

@@ -0,0 +1,122 @@
+require 'rdoc/task'
+
+module Rails
+  module API
+    class Task < RDoc::Task
+      RDOC_FILES = {
+        'activesupport' => {
+          :include => %w(
+            README.rdoc
+            CHANGELOG.md
+            lib/active_support/**/*.rb
+          ),
+          :exclude => 'lib/active_support/vendor/*'
+        },
+
+        'activerecord' => {
+          :include => %w(
+            README.rdoc
+            CHANGELOG.md
+            lib/active_record/**/*.rb
+          ),
+          :exclude => 'lib/active_record/vendor/*'
+        },
+
+        'activemodel' => {
+          :include => %w(
+            README.rdoc
+            CHANGELOG.md
+            lib/active_model/**/*.rb
+          )
+        },
+
+        'actionpack' => {
+          :include => %w(
+            README.rdoc
+            CHANGELOG.md
+            lib/abstract_controller/**/*.rb
+            lib/action_controller/**/*.rb
+            lib/action_dispatch/**/*.rb
+            lib/action_view/**/*.rb
+          ),
+          :exclude => 'lib/action_controller/vendor/*'
+        },
+
+        'actionmailer' => {
+          :include => %w(
+            README.rdoc
+            CHANGELOG.md
+            lib/action_mailer/**/*.rb
+          ),
+          :exclude => 'ib/action_mailer/vendor/*'
+        },
+
+        'railties' => {
+          :include => %w(
+            README.rdoc
+            CHANGELOG.md
+            MIT-LICENSE
+            lib/**/*.rb
+          )
+        }
+      }
+
+      def initialize(name)
+        super
+
+        self.title    = 'Ruby on Rails API'
+        self.rdoc_dir = api_dir
+
+        options << '-m'  << api_main
+        options << '-e'  << 'UTF-8'
+        options << '-f'  << 'sdoc'
+        options << '-T'  << 'rails'
+        options << '-g' # link to GitHub, SDoc flag
+
+        configure_rdoc_files
+
+        before_running_rdoc do
+          setup_horo_variables
+        end
+      end
+
+      # Hack, ignore the desc calls performed by the original initializer.
+      def desc(description)
+        # no-op
+      end
+
+      def configure_rdoc_files
+        rdoc_files.include(api_main)
+
+        RDOC_FILES.each do |component, cfg|
+          cdr = component_root_dir(component)
+
+          Array(cfg[:include]).each do |pattern|
+            rdoc_files.include("#{cdr}/#{pattern}")
+          end
+
+          Array(cfg[:exclude]).each do |pattern|
+            rdoc_files.exclude("#{cdr}/#{pattern}")
+          end
+        end
+      end
+
+      def api_main
+        'RDOC_MAIN.rdoc'
+      end
+
+      def api_dir
+        'doc/rdoc'
+      end
+
+      def component_root_dir(component)
+        component
+      end
+
+      def setup_horo_variables
+        ENV['HORO_PROJECT_NAME']    = 'Ruby on Rails'
+        ENV['HORO_PROJECT_VERSION'] = "master@#{`git rev-parse HEAD`[0, 7]}"
+      end
+    end
+  end
+end