From 5137d03cc5b2a5f0820bdcf11b0fffe5bf461470 Mon Sep 17 00:00:00 2001 From: Prem Sichanugrist Date: Sat, 1 Sep 2012 16:25:57 -0400 Subject: Rename the rest of the guides to Markdown --- guides/source/rails_application_templates.md | 215 +++++++++++++++++++++++++++ 1 file changed, 215 insertions(+) create mode 100644 guides/source/rails_application_templates.md (limited to 'guides/source/rails_application_templates.md') diff --git a/guides/source/rails_application_templates.md b/guides/source/rails_application_templates.md new file mode 100644 index 0000000000..2fa40bc4cc --- /dev/null +++ b/guides/source/rails_application_templates.md @@ -0,0 +1,215 @@ +h2. Rails Application Templates + +Application templates are simple Ruby files containing DSL for adding gems/initializers etc. to your freshly created Rails project or an existing Rails project. + +By referring to this guide, you will be able to: + +* Use templates to generate/customize Rails applications +* Write your own reusable application templates using the Rails template API + +endprologue. + +h3. Usage + +To apply a template, you need to provide the Rails generator with the location of the template you wish to apply, using -m option. This can either be path to a file or a URL. + + +$ rails new blog -m ~/template.rb +$ rails new blog -m http://example.com/template.rb + + +You can use the rake task +rails:template+ to apply templates to an existing Rails application. The location of the template needs to be passed in to an environment variable named LOCATION. Again, this can either be path to a file or a URL. + + +$ rake rails:template LOCATION=~/template.rb +$ rake rails:template LOCATION=http://example.com/template.rb + + +h3. Template API + +Rails templates API is very self explanatory and easy to understand. Here's an example of a typical Rails template: + + +# template.rb +run "rm public/index.html" +generate(:scaffold, "person name:string") +route "root :to => 'people#index'" +rake("db:migrate") + +git :init +git :add => "." +git :commit => %Q{ -m 'Initial commit' } + + +The following sections outlines the primary methods provided by the API: + +h4. gem(name, options = {}) + +Adds a +gem+ entry for the supplied gem to the generated application’s +Gemfile+. + +For example, if your application depends on the gems +bj+ and +nokogiri+: + + +gem "bj" +gem "nokogiri" + + +Please note that this will NOT install the gems for you and you will have to run +bundle install+ to do that. + + +bundle install + + +h4. gem_group(*names, &block) + +Wraps gem entries inside a group. + +For example, if you want to load +rspec-rails+ only in +development+ and +test+ group: + + +gem_group :development, :test do + gem "rspec-rails" +end + + +h4. add_source(source, options = {}) + +Adds the given source to the generated application's +Gemfile+. + +For example, if you need to source a gem from "http://code.whytheluckystiff.net": + + +add_source "http://code.whytheluckystiff.net" + + +h4. vendor/lib/file/initializer(filename, data = nil, &block) + +Adds an initializer to the generated application’s +config/initializers+ directory. + +Lets say you like using +Object#not_nil?+ and +Object#not_blank?+: + + +initializer 'bloatlol.rb', <<-CODE +class Object + def not_nil? + !nil? + end + + def not_blank? + !blank? + end +end +CODE + + +Similarly +lib()+ creates a file in the +lib/+ directory and +vendor()+ creates a file in the +vendor/+ directory. + +There is even +file()+, which accepts a relative path from +Rails.root+ and creates all the directories/file needed: + + +file 'app/components/foo.rb', <<-CODE +class Foo +end +CODE + + +That’ll create +app/components+ directory and put +foo.rb+ in there. + +h4. rakefile(filename, data = nil, &block) + +Creates a new rake file under +lib/tasks+ with the supplied tasks: + + +rakefile("bootstrap.rake") do + <<-TASK + namespace :boot do + task :strap do + puts "i like boots!" + end + end + TASK +end + + +The above creates +lib/tasks/bootstrap.rake+ with a +boot:strap+ rake task. + +h4. generate(what, args) + +Runs the supplied rails generator with given arguments. + + +generate(:scaffold, "person", "name:string", "address:text", "age:number") + + +h4. run(command) + +Executes an arbitrary command. Just like the backticks. Let's say you want to remove the +public/index.html+ file: + + +run "rm public/index.html" + + +h4. rake(command, options = {}) + +Runs the supplied rake tasks in the Rails application. Let's say you want to migrate the database: + + +rake "db:migrate" + + +You can also run rake tasks with a different Rails environment: + + +rake "db:migrate", :env => 'production' + + +h4. route(routing_code) + +This adds a routing entry to the +config/routes.rb+ file. In above steps, we generated a person scaffold and also removed +public/index.html+. Now to make +PeopleController#index+ as the default page for the application: + + +route "root :to => 'person#index'" + + +h4. inside(dir) + +Enables you to run a command from the given directory. For example, if you have a copy of edge rails that you wish to symlink from your new apps, you can do this: + + +inside('vendor') do + run "ln -s ~/commit-rails/rails rails" +end + + +h4. ask(question) + ++ask()+ gives you a chance to get some feedback from the user and use it in your templates. Lets say you want your user to name the new shiny library you’re adding: + + +lib_name = ask("What do you want to call the shiny library ?") +lib_name << ".rb" unless lib_name.index(".rb") + +lib lib_name, <<-CODE +class Shiny +end +CODE + + +h4. yes?(question) or no?(question) + +These methods let you ask questions from templates and decide the flow based on the user’s answer. Lets say you want to freeze rails only if the user want to: + + +rake("rails:freeze:gems") if yes?("Freeze rails gems ?") +no?(question) acts just the opposite. + + +h4. git(:command) + +Rails templates let you run any git command: + + +git :init +git :add => "." +git :commit => "-a -m 'Initial commit'" + -- cgit v1.2.3 From 7bc1ca351523949f6b4ce96018e95e61cbc7719e Mon Sep 17 00:00:00 2001 From: Prem Sichanugrist Date: Sat, 1 Sep 2012 17:08:06 -0400 Subject: Convert code blocks into GFM style --- guides/source/rails_application_templates.md | 76 ++++++++++++++-------------- 1 file changed, 38 insertions(+), 38 deletions(-) (limited to 'guides/source/rails_application_templates.md') diff --git a/guides/source/rails_application_templates.md b/guides/source/rails_application_templates.md index 2fa40bc4cc..1c5148f46f 100644 --- a/guides/source/rails_application_templates.md +++ b/guides/source/rails_application_templates.md @@ -13,23 +13,23 @@ h3. Usage To apply a template, you need to provide the Rails generator with the location of the template you wish to apply, using -m option. This can either be path to a file or a URL. - +```shell $ rails new blog -m ~/template.rb $ rails new blog -m http://example.com/template.rb - +``` You can use the rake task +rails:template+ to apply templates to an existing Rails application. The location of the template needs to be passed in to an environment variable named LOCATION. Again, this can either be path to a file or a URL. - +```shell $ rake rails:template LOCATION=~/template.rb $ rake rails:template LOCATION=http://example.com/template.rb - +``` h3. Template API Rails templates API is very self explanatory and easy to understand. Here's an example of a typical Rails template: - +```ruby # template.rb run "rm public/index.html" generate(:scaffold, "person name:string") @@ -39,7 +39,7 @@ rake("db:migrate") git :init git :add => "." git :commit => %Q{ -m 'Initial commit' } - +``` The following sections outlines the primary methods provided by the API: @@ -49,16 +49,16 @@ Adds a +gem+ entry for the supplied gem to the generated application’s +Gemfil For example, if your application depends on the gems +bj+ and +nokogiri+: - +```ruby gem "bj" gem "nokogiri" - +``` Please note that this will NOT install the gems for you and you will have to run +bundle install+ to do that. - +```ruby bundle install - +``` h4. gem_group(*names, &block) @@ -66,11 +66,11 @@ Wraps gem entries inside a group. For example, if you want to load +rspec-rails+ only in +development+ and +test+ group: - +```ruby gem_group :development, :test do gem "rspec-rails" end - +``` h4. add_source(source, options = {}) @@ -78,9 +78,9 @@ Adds the given source to the generated application's +Gemfile+. For example, if you need to source a gem from "http://code.whytheluckystiff.net": - +```ruby add_source "http://code.whytheluckystiff.net" - +``` h4. vendor/lib/file/initializer(filename, data = nil, &block) @@ -88,7 +88,7 @@ Adds an initializer to the generated application’s +config/initializers+ direc Lets say you like using +Object#not_nil?+ and +Object#not_blank?+: - +```ruby initializer 'bloatlol.rb', <<-CODE class Object def not_nil? @@ -100,18 +100,18 @@ class Object end end CODE - +``` Similarly +lib()+ creates a file in the +lib/+ directory and +vendor()+ creates a file in the +vendor/+ directory. There is even +file()+, which accepts a relative path from +Rails.root+ and creates all the directories/file needed: - +```ruby file 'app/components/foo.rb', <<-CODE class Foo end CODE - +``` That’ll create +app/components+ directory and put +foo.rb+ in there. @@ -119,7 +119,7 @@ h4. rakefile(filename, data = nil, &block) Creates a new rake file under +lib/tasks+ with the supplied tasks: - +```ruby rakefile("bootstrap.rake") do <<-TASK namespace :boot do @@ -129,7 +129,7 @@ rakefile("bootstrap.rake") do end TASK end - +``` The above creates +lib/tasks/bootstrap.rake+ with a +boot:strap+ rake task. @@ -137,55 +137,55 @@ h4. generate(what, args) Runs the supplied rails generator with given arguments. - +```ruby generate(:scaffold, "person", "name:string", "address:text", "age:number") - +``` h4. run(command) Executes an arbitrary command. Just like the backticks. Let's say you want to remove the +public/index.html+ file: - +```ruby run "rm public/index.html" - +``` h4. rake(command, options = {}) Runs the supplied rake tasks in the Rails application. Let's say you want to migrate the database: - +```ruby rake "db:migrate" - +``` You can also run rake tasks with a different Rails environment: - +```ruby rake "db:migrate", :env => 'production' - +``` h4. route(routing_code) This adds a routing entry to the +config/routes.rb+ file. In above steps, we generated a person scaffold and also removed +public/index.html+. Now to make +PeopleController#index+ as the default page for the application: - +```ruby route "root :to => 'person#index'" - +``` h4. inside(dir) Enables you to run a command from the given directory. For example, if you have a copy of edge rails that you wish to symlink from your new apps, you can do this: - +```ruby inside('vendor') do run "ln -s ~/commit-rails/rails rails" end - +``` h4. ask(question) +ask()+ gives you a chance to get some feedback from the user and use it in your templates. Lets say you want your user to name the new shiny library you’re adding: - +```ruby lib_name = ask("What do you want to call the shiny library ?") lib_name << ".rb" unless lib_name.index(".rb") @@ -193,23 +193,23 @@ lib lib_name, <<-CODE class Shiny end CODE - +``` h4. yes?(question) or no?(question) These methods let you ask questions from templates and decide the flow based on the user’s answer. Lets say you want to freeze rails only if the user want to: - +```ruby rake("rails:freeze:gems") if yes?("Freeze rails gems ?") no?(question) acts just the opposite. - +``` h4. git(:command) Rails templates let you run any git command: - +```ruby git :init git :add => "." git :commit => "-a -m 'Initial commit'" - +``` -- cgit v1.2.3 From 872b7af337196febc516cb6218ae3d07f01a11a8 Mon Sep 17 00:00:00 2001 From: Prem Sichanugrist Date: Sat, 1 Sep 2012 17:25:58 -0400 Subject: Convert heading tags and heading section --- guides/source/rails_application_templates.md | 37 +++++++++++++++------------- 1 file changed, 20 insertions(+), 17 deletions(-) (limited to 'guides/source/rails_application_templates.md') diff --git a/guides/source/rails_application_templates.md b/guides/source/rails_application_templates.md index 1c5148f46f..c03eb1d0be 100644 --- a/guides/source/rails_application_templates.md +++ b/guides/source/rails_application_templates.md @@ -1,4 +1,5 @@ -h2. Rails Application Templates +Rails Application Templates +=========================== Application templates are simple Ruby files containing DSL for adding gems/initializers etc. to your freshly created Rails project or an existing Rails project. @@ -7,9 +8,10 @@ By referring to this guide, you will be able to: * Use templates to generate/customize Rails applications * Write your own reusable application templates using the Rails template API -endprologue. +-------------------------------------------------------------------------------- -h3. Usage +Usage +----- To apply a template, you need to provide the Rails generator with the location of the template you wish to apply, using -m option. This can either be path to a file or a URL. @@ -25,7 +27,8 @@ $ rake rails:template LOCATION=~/template.rb $ rake rails:template LOCATION=http://example.com/template.rb ``` -h3. Template API +Template API +------------ Rails templates API is very self explanatory and easy to understand. Here's an example of a typical Rails template: @@ -43,7 +46,7 @@ git :commit => %Q{ -m 'Initial commit' } The following sections outlines the primary methods provided by the API: -h4. gem(name, options = {}) +### gem(name, options = {}) Adds a +gem+ entry for the supplied gem to the generated application’s +Gemfile+. @@ -60,7 +63,7 @@ Please note that this will NOT install the gems for you and you will have to run bundle install ``` -h4. gem_group(*names, &block) +### gem_group(*names, &block) Wraps gem entries inside a group. @@ -72,7 +75,7 @@ gem_group :development, :test do end ``` -h4. add_source(source, options = {}) +### add_source(source, options = {}) Adds the given source to the generated application's +Gemfile+. @@ -82,7 +85,7 @@ For example, if you need to source a gem from "http://code.whytheluckystiff.net" add_source "http://code.whytheluckystiff.net" ``` -h4. vendor/lib/file/initializer(filename, data = nil, &block) +### vendor/lib/file/initializer(filename, data = nil, &block) Adds an initializer to the generated application’s +config/initializers+ directory. @@ -115,7 +118,7 @@ CODE That’ll create +app/components+ directory and put +foo.rb+ in there. -h4. rakefile(filename, data = nil, &block) +### rakefile(filename, data = nil, &block) Creates a new rake file under +lib/tasks+ with the supplied tasks: @@ -133,7 +136,7 @@ end The above creates +lib/tasks/bootstrap.rake+ with a +boot:strap+ rake task. -h4. generate(what, args) +### generate(what, args) Runs the supplied rails generator with given arguments. @@ -141,7 +144,7 @@ Runs the supplied rails generator with given arguments. generate(:scaffold, "person", "name:string", "address:text", "age:number") ``` -h4. run(command) +### run(command) Executes an arbitrary command. Just like the backticks. Let's say you want to remove the +public/index.html+ file: @@ -149,7 +152,7 @@ Executes an arbitrary command. Just like the backticks. Let's say you want to re run "rm public/index.html" ``` -h4. rake(command, options = {}) +### rake(command, options = {}) Runs the supplied rake tasks in the Rails application. Let's say you want to migrate the database: @@ -163,7 +166,7 @@ You can also run rake tasks with a different Rails environment: rake "db:migrate", :env => 'production' ``` -h4. route(routing_code) +### route(routing_code) This adds a routing entry to the +config/routes.rb+ file. In above steps, we generated a person scaffold and also removed +public/index.html+. Now to make +PeopleController#index+ as the default page for the application: @@ -171,7 +174,7 @@ This adds a routing entry to the +config/routes.rb+ file. In above steps, we gen route "root :to => 'person#index'" ``` -h4. inside(dir) +### inside(dir) Enables you to run a command from the given directory. For example, if you have a copy of edge rails that you wish to symlink from your new apps, you can do this: @@ -181,7 +184,7 @@ inside('vendor') do end ``` -h4. ask(question) +### ask(question) +ask()+ gives you a chance to get some feedback from the user and use it in your templates. Lets say you want your user to name the new shiny library you’re adding: @@ -195,7 +198,7 @@ end CODE ``` -h4. yes?(question) or no?(question) +### yes?(question) or no?(question) These methods let you ask questions from templates and decide the flow based on the user’s answer. Lets say you want to freeze rails only if the user want to: @@ -204,7 +207,7 @@ rake("rails:freeze:gems") if yes?("Freeze rails gems ?") no?(question) acts just the opposite. ``` -h4. git(:command) +### git(:command) Rails templates let you run any git command: -- cgit v1.2.3 From 21a0b20e397e1b86336f19983c4ee8c368ef55e7 Mon Sep 17 00:00:00 2001 From: Prem Sichanugrist Date: Sat, 1 Sep 2012 20:45:26 -0400 Subject: change shell to bash --- guides/source/rails_application_templates.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'guides/source/rails_application_templates.md') diff --git a/guides/source/rails_application_templates.md b/guides/source/rails_application_templates.md index c03eb1d0be..b28c8d5e20 100644 --- a/guides/source/rails_application_templates.md +++ b/guides/source/rails_application_templates.md @@ -15,14 +15,14 @@ Usage To apply a template, you need to provide the Rails generator with the location of the template you wish to apply, using -m option. This can either be path to a file or a URL. -```shell +```bash $ rails new blog -m ~/template.rb $ rails new blog -m http://example.com/template.rb ``` You can use the rake task +rails:template+ to apply templates to an existing Rails application. The location of the template needs to be passed in to an environment variable named LOCATION. Again, this can either be path to a file or a URL. -```shell +```bash $ rake rails:template LOCATION=~/template.rb $ rake rails:template LOCATION=http://example.com/template.rb ``` -- cgit v1.2.3 From 31ef4cf656785a190723d2d8fb4c0fd06f4009bc Mon Sep 17 00:00:00 2001 From: Prem Sichanugrist Date: Sat, 1 Sep 2012 21:37:59 -0400 Subject: Convert all inline codes to Markdown syntax --- guides/source/rails_application_templates.md | 32 ++++++++++++++-------------- 1 file changed, 16 insertions(+), 16 deletions(-) (limited to 'guides/source/rails_application_templates.md') diff --git a/guides/source/rails_application_templates.md b/guides/source/rails_application_templates.md index b28c8d5e20..f0585efb11 100644 --- a/guides/source/rails_application_templates.md +++ b/guides/source/rails_application_templates.md @@ -20,7 +20,7 @@ $ rails new blog -m ~/template.rb $ rails new blog -m http://example.com/template.rb ``` -You can use the rake task +rails:template+ to apply templates to an existing Rails application. The location of the template needs to be passed in to an environment variable named LOCATION. Again, this can either be path to a file or a URL. +You can use the rake task `rails:template` to apply templates to an existing Rails application. The location of the template needs to be passed in to an environment variable named LOCATION. Again, this can either be path to a file or a URL. ```bash $ rake rails:template LOCATION=~/template.rb @@ -48,16 +48,16 @@ The following sections outlines the primary methods provided by the API: ### gem(name, options = {}) -Adds a +gem+ entry for the supplied gem to the generated application’s +Gemfile+. +Adds a `gem` entry for the supplied gem to the generated application’s `Gemfile`. -For example, if your application depends on the gems +bj+ and +nokogiri+: +For example, if your application depends on the gems `bj` and `nokogiri`: ```ruby gem "bj" gem "nokogiri" ``` -Please note that this will NOT install the gems for you and you will have to run +bundle install+ to do that. +Please note that this will NOT install the gems for you and you will have to run `bundle install` to do that. ```ruby bundle install @@ -67,7 +67,7 @@ bundle install Wraps gem entries inside a group. -For example, if you want to load +rspec-rails+ only in +development+ and +test+ group: +For example, if you want to load `rspec-rails` only in `development` and `test` group: ```ruby gem_group :development, :test do @@ -77,7 +77,7 @@ end ### add_source(source, options = {}) -Adds the given source to the generated application's +Gemfile+. +Adds the given source to the generated application's `Gemfile`. For example, if you need to source a gem from "http://code.whytheluckystiff.net": @@ -87,9 +87,9 @@ add_source "http://code.whytheluckystiff.net" ### vendor/lib/file/initializer(filename, data = nil, &block) -Adds an initializer to the generated application’s +config/initializers+ directory. +Adds an initializer to the generated application’s `config/initializers` directory. -Lets say you like using +Object#not_nil?+ and +Object#not_blank?+: +Lets say you like using `Object#not_nil?` and `Object#not_blank?`: ```ruby initializer 'bloatlol.rb', <<-CODE @@ -105,9 +105,9 @@ end CODE ``` -Similarly +lib()+ creates a file in the +lib/+ directory and +vendor()+ creates a file in the +vendor/+ directory. +Similarly `lib()` creates a file in the `lib/` directory and `vendor()` creates a file in the `vendor/` directory. -There is even +file()+, which accepts a relative path from +Rails.root+ and creates all the directories/file needed: +There is even `file()`, which accepts a relative path from `Rails.root` and creates all the directories/file needed: ```ruby file 'app/components/foo.rb', <<-CODE @@ -116,11 +116,11 @@ end CODE ``` -That’ll create +app/components+ directory and put +foo.rb+ in there. +That’ll create `app/components` directory and put `foo.rb` in there. ### rakefile(filename, data = nil, &block) -Creates a new rake file under +lib/tasks+ with the supplied tasks: +Creates a new rake file under `lib/tasks` with the supplied tasks: ```ruby rakefile("bootstrap.rake") do @@ -134,7 +134,7 @@ rakefile("bootstrap.rake") do end ``` -The above creates +lib/tasks/bootstrap.rake+ with a +boot:strap+ rake task. +The above creates `lib/tasks/bootstrap.rake` with a `boot:strap` rake task. ### generate(what, args) @@ -146,7 +146,7 @@ generate(:scaffold, "person", "name:string", "address:text", "age:number") ### run(command) -Executes an arbitrary command. Just like the backticks. Let's say you want to remove the +public/index.html+ file: +Executes an arbitrary command. Just like the backticks. Let's say you want to remove the `public/index.html` file: ```ruby run "rm public/index.html" @@ -168,7 +168,7 @@ rake "db:migrate", :env => 'production' ### route(routing_code) -This adds a routing entry to the +config/routes.rb+ file. In above steps, we generated a person scaffold and also removed +public/index.html+. Now to make +PeopleController#index+ as the default page for the application: +This adds a routing entry to the `config/routes.rb` file. In above steps, we generated a person scaffold and also removed `public/index.html`. Now to make `PeopleController#index` as the default page for the application: ```ruby route "root :to => 'person#index'" @@ -186,7 +186,7 @@ end ### ask(question) -+ask()+ gives you a chance to get some feedback from the user and use it in your templates. Lets say you want your user to name the new shiny library you’re adding: +`ask()` gives you a chance to get some feedback from the user and use it in your templates. Lets say you want your user to name the new shiny library you’re adding: ```ruby lib_name = ask("What do you want to call the shiny library ?") -- cgit v1.2.3 From 721afdcc4b58c65f36122b10ec998b913a147912 Mon Sep 17 00:00:00 2001 From: Prem Sichanugrist Date: Mon, 3 Sep 2012 21:21:24 -0400 Subject: Fix remaining formatting problems in the guide --- guides/source/rails_application_templates.md | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) (limited to 'guides/source/rails_application_templates.md') diff --git a/guides/source/rails_application_templates.md b/guides/source/rails_application_templates.md index f0585efb11..ee5fbcfd52 100644 --- a/guides/source/rails_application_templates.md +++ b/guides/source/rails_application_templates.md @@ -59,7 +59,7 @@ gem "nokogiri" Please note that this will NOT install the gems for you and you will have to run `bundle install` to do that. -```ruby +```bash bundle install ``` @@ -93,15 +93,15 @@ Lets say you like using `Object#not_nil?` and `Object#not_blank?`: ```ruby initializer 'bloatlol.rb', <<-CODE -class Object - def not_nil? - !nil? - end + class Object + def not_nil? + !nil? + end - def not_blank? - !blank? + def not_blank? + !blank? + end end -end CODE ``` @@ -111,8 +111,8 @@ There is even `file()`, which accepts a relative path from `Rails.root` and crea ```ruby file 'app/components/foo.rb', <<-CODE -class Foo -end + class Foo + end CODE ``` @@ -193,8 +193,8 @@ lib_name = ask("What do you want to call the shiny library ?") lib_name << ".rb" unless lib_name.index(".rb") lib lib_name, <<-CODE -class Shiny -end + class Shiny + end CODE ``` @@ -204,7 +204,7 @@ These methods let you ask questions from templates and decide the flow based on ```ruby rake("rails:freeze:gems") if yes?("Freeze rails gems ?") -no?(question) acts just the opposite. +# no?(question) acts just the opposite. ``` ### git(:command) -- cgit v1.2.3