Skip to content
This repository
Browse code

Rework a bit README files.

  • Loading branch information...
commit b70062f1e71dc8bda8e9b8159a1f202389a80a62 1 parent cd15368
José Valim josevalim authored
58 README
... ... @@ -0,0 +1,58 @@
  1 +== Welcome to Rails
  2 +
  3 +Rails is a web-application framework that includes everything needed to create
  4 +database-backed web applications according to the Model-View-Control pattern.
  5 +
  6 +This pattern splits the view (also called the presentation) into "dumb"
  7 +templates that are primarily responsible for inserting pre-built data in between
  8 +HTML tags. The model contains the "smart" domain objects (such as Account,
  9 +Product, Person, Post) that holds all the business logic and knows how to
  10 +persist themselves to a database. The controller handles the incoming requests
  11 +(such as Save New Account, Update Product, Show Post) by manipulating the model
  12 +and directing data to the view.
  13 +
  14 +In Rails, the model is handled by what's called an object-relational mapping
  15 +layer entitled Active Record. This layer allows you to present the data from
  16 +database rows as objects and embellish these data objects with business logic
  17 +methods. You can read more about Active Record in
  18 +link:files/vendor/rails/activerecord/README.html.
  19 +
  20 +The controller and view are handled by the Action Pack, which handles both
  21 +layers by its two parts: Action View and Action Controller. These two layers
  22 +are bundled in a single package due to their heavy interdependence. This is
  23 +unlike the relationship between the Active Record and Action Pack that is much
  24 +more separate. Each of these packages can be used independently outside of
  25 +Rails. You can read more about Action Pack in
  26 +link:files/vendor/rails/actionpack/README.html.
  27 +
  28 +
  29 +== Getting Started
  30 +
  31 +1. Install Rails at the command prompt if you haven't yet:
  32 + <tt>gem install rails</tt>
  33 +
  34 +2. At the command prompt, create a new Rails application:
  35 + <tt>rails new myapp</tt> (where <tt>myapp</tt> is the application name)
  36 +
  37 +3. Change directory to <tt>myapp</tt> and start the web server:
  38 + <tt>cd myapp; rails server</tt> (run with --help for options)
  39 +
  40 +4. Go to http://localhost:3000/ and you'll see:
  41 + "Welcome aboard: You're riding Ruby on Rails!"
  42 +
  43 +5. Follow the guidelines to start developing your application. You can find
  44 +the following resources handy:
  45 +
  46 +* The README file created within your application
  47 +* The Getting Started Guide: http://guides.rubyonrails.org/getting_started.html
  48 +* Ruby on Rails Tutorial Book: http://www.railstutorial.org/
  49 +
  50 +
  51 +== Contributing
  52 +
  53 +Check out the contributing guide at http://edgeguides.rubyonrails.org/contributing_to_rails.html
  54 +
  55 +
  56 +== License
  57 +
  58 +Ruby on Rails is released under the MIT license.
9 actionpack/README
@@ -19,15 +19,6 @@ the HTML. To avoid cluttering the templates with code, a bunch of helper
19 19 classes provide common behavior for forms, dates, and strings. And it's easy
20 20 to add specific helpers to keep the separation as the application evolves.
21 21
22   -Note: Some of the features, such as scaffolding and form building, are tied to
23   -ActiveRecord[http://activerecord.rubyonrails.org] (an object-relational
24   -mapping package), but that doesn't mean that Action Pack depends on Active
25   -Record. Action Pack is an independent package that can be used with any sort
26   -of backend (Instiki[http://www.instiki.org], which is based on an older version
27   -of Action Pack, used Madeleine for example). Read more about the role Action
28   -Pack can play when used together with Active Record on
29   -http://www.rubyonrails.org.
30   -
31 22 A short rundown of the major features:
32 23
33 24 * Actions grouped in controller as methods instead of separate command objects
280 railties/README
... ... @@ -1,281 +1,25 @@
1   -== Welcome to Rails
  1 += Railties -- Gluing the Engine to the Rails
2 2
3   -Rails is a web-application framework that includes everything needed to create
4   -database-backed web applications according to the Model-View-Control pattern.
  3 +Railties is responsible to glue all frameworks together. Overall, it:
5 4
6   -This pattern splits the view (also called the presentation) into "dumb"
7   -templates that are primarily responsible for inserting pre-built data in between
8   -HTML tags. The model contains the "smart" domain objects (such as Account,
9   -Product, Person, Post) that holds all the business logic and knows how to
10   -persist themselves to a database. The controller handles the incoming requests
11   -(such as Save New Account, Update Product, Show Post) by manipulating the model
12   -and directing data to the view.
  5 +* handles all the bootstrapping process for a Rails application;
13 6
14   -In Rails, the model is handled by what's called an object-relational mapping
15   -layer entitled Active Record. This layer allows you to present the data from
16   -database rows as objects and embellish these data objects with business logic
17   -methods. You can read more about Active Record in
18   -link:files/vendor/rails/activerecord/README.html.
  7 +* manager rails command line interface;
19 8
20   -The controller and view are handled by the Action Pack, which handles both
21   -layers by its two parts: Action View and Action Controller. These two layers
22   -are bundled in a single package due to their heavy interdependence. This is
23   -unlike the relationship between the Active Record and Action Pack that is much
24   -more separate. Each of these packages can be used independently outside of
25   -Rails. You can read more about Action Pack in
26   -link:files/vendor/rails/actionpack/README.html.
  9 +* provides Rails generators core;
27 10
28 11
29   -== Getting Started
  12 +== Download
30 13
31   -1. At the command prompt, create a new Rails application:
32   - <tt>rails new myapp</tt> (where <tt>myapp</tt> is the application name)
  14 +The latest version of Railties can be installed with Rubygems:
33 15
34   -2. Change directory to <tt>myapp</tt> and start the web server:
35   - <tt>cd myapp; rails server</tt> (run with --help for options)
  16 +* gem install railties
36 17
37   -3. Go to http://localhost:3000/ and you'll see:
38   - "Welcome aboard: You're riding Ruby on Rails!"
  18 +Documentation can be found at
39 19
40   -4. Follow the guidelines to start developing your application. You can find
41   -the following resources handy:
  20 +* http://api.rubyonrails.org
42 21
43   -* The Getting Started Guide: http://guides.rubyonrails.org/getting_started.html
44   -* Ruby on Rails Tutorial Book: http://www.railstutorial.org/
45 22
  23 +== License
46 24
47   -== Web Servers
48   -
49   -By default, Rails will try to use Mongrel if it's installed when started with
50   -<tt>rails server</tt>, otherwise Rails will use WEBrick, the web server that
51   -ships with Ruby.
52   -
53   -Mongrel is a Ruby-based web server with a C component (which requires
54   -compilation) that is suitable for development. If you have Ruby Gems installed,
55   -getting up and running with mongrel is as easy as:
56   - <tt>sudo gem install mongrel</tt>.
57   -
58   -You can find more info at: http://mongrel.rubyforge.org
59   -
60   -You can alternatively run Rails applications with other Ruby web servers, e.g.,
61   -{Thin}[http://code.macournoyer.com/thin/], {Ebb}[http://ebb.rubyforge.org/], and
62   -Apache with {mod_rails}[http://www.modrails.com/]. However, <tt>rails server</tt>
63   -doesn't search for or start them.
64   -
65   -For production use, often a web/proxy server, e.g., {Apache}[http://apache.org],
66   -{Nginx}[http://nginx.net/], {LiteSpeed}[http://litespeedtech.com/],
67   -{Lighttpd}[http://www.lighttpd.net/], or {IIS}[http://www.iis.net/], is deployed
68   -as the front end server with the chosen Ruby web server running in the back end
69   -and receiving the proxied requests via one of several protocols (HTTP, CGI, FCGI).
70   -
71   -
72   -== Debugging Rails
73   -
74   -Sometimes your application goes wrong. Fortunately there are a lot of tools that
75   -will help you debug it and get it back on the rails.
76   -
77   -First area to check is the application log files. Have "tail -f" commands
78   -running on the server.log and development.log. Rails will automatically display
79   -debugging and runtime information to these files. Debugging info will also be
80   -shown in the browser on requests from 127.0.0.1.
81   -
82   -You can also log your own messages directly into the log file from your code
83   -using the Ruby logger class from inside your controllers. Example:
84   -
85   - class WeblogController < ActionController::Base
86   - def destroy
87   - @weblog = Weblog.find(params[:id])
88   - @weblog.destroy
89   - logger.info("#{Time.now} Destroyed Weblog ID ##{@weblog.id}!")
90   - end
91   - end
92   -
93   -The result will be a message in your log file along the lines of:
94   -
95   - Mon Oct 08 14:22:29 +1000 2007 Destroyed Weblog ID #1!
96   -
97   -More information on how to use the logger is at http://www.ruby-doc.org/core/
98   -
99   -Also, Ruby documentation can be found at http://www.ruby-lang.org/. There are
100   -several books available online as well:
101   -
102   -* Programming Ruby: http://www.ruby-doc.org/docs/ProgrammingRuby/ (Pickaxe)
103   -* Learn to Program: http://pine.fm/LearnToProgram/ (a beginners guide)
104   -
105   -These two books will bring you up to speed on the Ruby language and also on
106   -programming in general.
107   -
108   -
109   -== Debugger
110   -
111   -Debugger support is available through the debugger command when you start your
112   -Mongrel or WEBrick server with --debugger. This means that you can break out of
113   -execution at any point in the code, investigate and change the model, and then,
114   -resume execution! You need to install ruby-debug to run the server in debugging
115   -mode. With gems, use <tt>sudo gem install ruby-debug</tt>. Example:
116   -
117   - class WeblogController < ActionController::Base
118   - def index
119   - @posts = Post.find(:all)
120   - debugger
121   - end
122   - end
123   -
124   -So the controller will accept the action, run the first line, then present you
125   -with a IRB prompt in the server window. Here you can do things like:
126   -
127   - >> @posts.inspect
128   - => "[#<Post:0x14a6be8
129   - @attributes={"title"=>nil, "body"=>nil, "id"=>"1"}>,
130   - #<Post:0x14a6620
131   - @attributes={"title"=>"Rails", "body"=>"Only ten..", "id"=>"2"}>]"
132   - >> @posts.first.title = "hello from a debugger"
133   - => "hello from a debugger"
134   -
135   -...and even better, you can examine how your runtime objects actually work:
136   -
137   - >> f = @posts.first
138   - => #<Post:0x13630c4 @attributes={"title"=>nil, "body"=>nil, "id"=>"1"}>
139   - >> f.
140   - Display all 152 possibilities? (y or n)
141   -
142   -Finally, when you're ready to resume execution, you can enter "cont".
143   -
144   -
145   -== Console
146   -
147   -The console is a Ruby shell, which allows you to interact with your
148   -application's domain model. Here you'll have all parts of the application
149   -configured, just like it is when the application is running. You can inspect
150   -domain models, change values, and save to the database. Starting the script
151   -without arguments will launch it in the development environment.
152   -
153   -To start the console, run <tt>rails console</tt> from the application
154   -directory.
155   -
156   -Options:
157   -
158   -* Passing the <tt>-s, --sandbox</tt> argument will rollback any modifications
159   - made to the database.
160   -* Passing an environment name as an argument will load the corresponding
161   - environment. Example: <tt>rails console production</tt>.
162   -
163   -To reload your controllers and models after launching the console run
164   -<tt>reload!</tt>
165   -
166   -More information about irb can be found at:
167   -link:http://www.rubycentral.com/pickaxe/irb.html
168   -
169   -
170   -== dbconsole
171   -
172   -You can go to the command line of your database directly through <tt>rails
173   -dbconsole</tt>. You would be connected to the database with the credentials
174   -defined in database.yml. Starting the script without arguments will connect you
175   -to the development database. Passing an argument will connect you to a different
176   -database, like <tt>rails dbconsole production</tt>. Currently works for MySQL,
177   -PostgreSQL and SQLite 3.
178   -
179   -== Description of Contents
180   -
181   -The default directory structure of a generated Ruby on Rails application:
182   -
183   - |-- app
184   - | |-- controllers
185   - | |-- helpers
186   - | |-- models
187   - | `-- views
188   - | `-- layouts
189   - |-- config
190   - | |-- environments
191   - | |-- initializers
192   - | `-- locales
193   - |-- db
194   - |-- doc
195   - |-- lib
196   - | `-- tasks
197   - |-- log
198   - |-- public
199   - | |-- images
200   - | |-- javascripts
201   - | `-- stylesheets
202   - |-- script
203   - | `-- performance
204   - |-- test
205   - | |-- fixtures
206   - | |-- functional
207   - | |-- integration
208   - | |-- performance
209   - | `-- unit
210   - |-- tmp
211   - | |-- cache
212   - | |-- pids
213   - | |-- sessions
214   - | `-- sockets
215   - `-- vendor
216   - `-- plugins
217   -
218   -app
219   - Holds all the code that's specific to this particular application.
220   -
221   -app/controllers
222   - Holds controllers that should be named like weblogs_controller.rb for
223   - automated URL mapping. All controllers should descend from
224   - ApplicationController which itself descends from ActionController::Base.
225   -
226   -app/models
227   - Holds models that should be named like post.rb. Models descend from
228   - ActiveRecord::Base by default.
229   -
230   -app/views
231   - Holds the template files for the view that should be named like
232   - weblogs/index.html.erb for the WeblogsController#index action. All views use
233   - eRuby syntax by default.
234   -
235   -app/views/layouts
236   - Holds the template files for layouts to be used with views. This models the
237   - common header/footer method of wrapping views. In your views, define a layout
238   - using the <tt>layout :default</tt> and create a file named default.html.erb.
239   - Inside default.html.erb, call <% yield %> to render the view using this
240   - layout.
241   -
242   -app/helpers
243   - Holds view helpers that should be named like weblogs_helper.rb. These are
244   - generated for you automatically when using generators for controllers.
245   - Helpers can be used to wrap functionality for your views into methods.
246   -
247   -config
248   - Configuration files for the Rails environment, the routing map, the database,
249   - and other dependencies.
250   -
251   -db
252   - Contains the database schema in schema.rb. db/migrate contains all the
253   - sequence of Migrations for your schema.
254   -
255   -doc
256   - This directory is where your application documentation will be stored when
257   - generated using <tt>rake doc:app</tt>
258   -
259   -lib
260   - Application specific libraries. Basically, any kind of custom code that
261   - doesn't belong under controllers, models, or helpers. This directory is in
262   - the load path.
263   -
264   -public
265   - The directory available for the web server. Contains subdirectories for
266   - images, stylesheets, and javascripts. Also contains the dispatchers and the
267   - default HTML files. This should be set as the DOCUMENT_ROOT of your web
268   - server.
269   -
270   -script
271   - Helper scripts for automation and generation.
272   -
273   -test
274   - Unit and functional tests along with fixtures. When using the rails generate
275   - command, template test files will be generated for you and placed in this
276   - directory.
277   -
278   -vendor
279   - External libraries that the application depends on. Also includes the plugins
280   - subdirectory. If the app has frozen rails, those gems also go here, under
281   - vendor/rails/. This directory is in the load path.
  25 +Railties is released under the MIT license.
7 railties/Rakefile
@@ -35,13 +35,6 @@ end
35 35
36 36 # Update spinoffs -------------------------------------------------------------------
37 37
38   -desc "Updates application README to the latest version Railties README"
39   -task :update_readme do
40   - readme = "lib/rails/generators/rails/app/templates/README"
41   - rm readme
42   - cp "./README", readme
43   -end
44   -
45 38 desc 'Generate guides (for authors), use ONLY=foo to process just "foo.textile"'
46 39 task :generate_guides do
47 40 ENV["WARN_BROKEN_LINKS"] = "1" # authors can't disable this

0 comments on commit b70062f

Please sign in to comment.
Something went wrong with that request. Please try again.