diff options
| -rw-r--r-- | .gitignore | 1 | ||||
| -rw-r--r-- | RDOC_MAIN.rdoc | 73 | ||||
| -rw-r--r-- | Rakefile | 85 | ||||
| -rw-r--r-- | railties/lib/rails/api/task.rb | 122 |
4 files changed, 197 insertions, 84 deletions
diff --git a/.gitignore b/.gitignore index 4c2c8de10c..7236e395a2 100644 --- a/.gitignore +++ b/.gitignore @@ -20,4 +20,3 @@ pkg /railties/doc /railties/tmp /guides/output -/RDOC_MAIN.rdoc diff --git a/RDOC_MAIN.rdoc b/RDOC_MAIN.rdoc new file mode 100644 index 0000000000..cadf0fb43e --- /dev/null +++ b/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]. @@ -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 diff --git a/railties/lib/rails/api/task.rb b/railties/lib/rails/api/task.rb new file mode 100644 index 0000000000..92bd192468 --- /dev/null +++ b/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 |