mirror of https://github.com/rails/rails
encapsulates API generation in Rails::API::Task
This commit is contained in:
Xavier Noria
parent
ab6cdf7e74
commit
7a5aa720c4
|
|
@ -20,4 +20,3 @@ pkg
|
|||
/railties/doc
|
||||
/railties/tmp
|
||||
/guides/output
|
||||
/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].
|
||||
85
Rakefile
85
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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
Loading…
Reference in New Issue