Permalink
Browse files

Merge pull request #6502 from rafmagana/guides_refactor_rakefile

[Guides] refactor rakefile to have a :guides namespace and a task that shows help
  • Loading branch information...
2 parents 70ad12a + eb362e5 commit 669694fe888053ccc86e9a9d1d19adb8dba5fafb @fxn fxn committed May 29, 2012
Showing with 89 additions and 22 deletions.
  1. +69 −9 guides/Rakefile
  2. +2 −7 guides/rails_guides/generator.rb
  3. +18 −6 guides/source/ruby_on_rails_guides_guidelines.textile
View
@@ -1,11 +1,71 @@
-desc 'Generate guides (for authors), use ONLY=foo to process just "foo.textile"'
-task :generate_guides do
- ENV["WARN_BROKEN_LINKS"] = "1" # authors can't disable this
- ruby "rails_guides.rb"
-end
+namespace :guides do
+
+ desc 'Generate guides (for authors), use ONLY=foo to process just "foo.textile"'
+ task :generate => 'generate:html'
+
+ namespace :generate do
+
+ desc "Generate HTML guides"
+ task :html do
+ ENV["WARN_BROKEN_LINKS"] = "1" # authors can't disable this
+ ruby "rails_guides.rb"
+ end
+
+ desc "Generate .mobi file. The kindlegen executable must be in your PATH. You can get it for free from http://www.amazon.com/kindlepublishing"
+ task :kindle do
+ ENV['KINDLE'] = '1'
+ Rake::Task['guides:generate:html'].invoke
+ end
+ end
+
+ # Validate guides -------------------------------------------------------------------------
+ desc 'Validate guides, use ONLY=foo to process just "foo.html"'
+ task :validate do
+ ruby "w3c_validator.rb"
+ end
+
+ desc "Show help"
+ task :help do
+ puts <<-help
+
+Guides are taken from the source directory, and the resulting HTML goes into the
+output directory. Assets are stored under files, and copied to output/files as
+part of the generation process.
+
+All this process is handled via rake tasks, here's a full list of them:
-# Validate guides -------------------------------------------------------------------------
-desc 'Validate guides, use ONLY=foo to process just "foo.html"'
-task :validate_guides do
- ruby "w3c_validator.rb"
+#{%x[rake -T]}
+Some arguments may be passed via environment variables:
+
+ WARNINGS=1
+ Internal links (anchors) are checked, also detects duplicated IDs.
+
+ ALL=1
+ Force generation of all guides.
+
+ ONLY=name
+ Useful if you want to generate only one or a set of guides.
+
+ Generate only association_basics.html:
+ ONLY=assoc
+
+ Separate many using commas:
+ ONLY=assoc,migrations
+
+ GUIDES_LANGUAGE
+ Use it when you want to generate translated guides in
+ source/<GUIDES_LANGUAGE> folder (such as source/es)
+
+ EDGE=1
+ Indicate generated guides should be marked as edge.
+
+Examples:
+ $ rake guides:generate ALL=1
+ $ rake guides:generate EDGE=1
+ $ rake guides:generate:kindle EDGE=1
+ $ rake guides:generate GUIDES_LANGUAGE=es
+ help
+ end
end
+
+task :default => 'guides:help'
@@ -1,7 +1,7 @@
# ---------------------------------------------------------------------------
#
-# This script generates the guides. It can be invoked either directly or via the
-# generate_guides rake task within the railties directory.
+# This script generates the guides. It can be invoked via the
+# guides:generate rake task within the guides directory.
#
# Guides are taken from the source directory, and the resulting HTML goes into the
# output directory. Assets are stored under files, and copied to output/files as
@@ -47,11 +47,6 @@
# Set to "1" to indicate generated guides should be marked as edge. This
# inserts a badge and changes the preamble of the home page.
#
-# KINDLE
-# Set to "1" to generate the .mobi with all the guides. The kindlegen
-# executable must be in your PATH. You can get it for free from
-# http://www.amazon.com/kindlepublishing
-#
# ---------------------------------------------------------------------------
require 'set'
@@ -47,7 +47,13 @@ h4. Generation
To generate all the guides, just +cd+ into the *+guides+* directory and execute:
<plain>
-bundle exec rake generate_guides
+bundle exec rake guides:generate
+</plain>
+
+or
+
+<plain>
+bundle exec rake guides:generate:html
</plain>
(You may need to run +bundle install+ first to install the required gems.)
@@ -56,7 +62,7 @@ To process +my_guide.textile+ and nothing else use the +ONLY+ environment variab
<plain>
touch my_guide.textile
-bundle exec rake generate_guides ONLY=my_guide
+bundle exec rake guides:generate ONLY=my_guide
</plain>
By default, guides that have not been modified are not processed, so +ONLY+ is rarely needed in practice.
@@ -68,15 +74,21 @@ It is also recommended that you work with +WARNINGS=1+. This detects duplicate I
If you want to generate guides in a language other than English, you can keep them in a separate directory under +source+ (eg. <tt>source/es</tt>) and use the +GUIDES_LANGUAGE+ environment variable:
<plain>
-bundle exec rake generate_guides GUIDES_LANGUAGE=es
+bundle exec rake guides:generate GUIDES_LANGUAGE=es
+</plain>
+
+If you want to see all the environment variables you can use to configure the generation script just run:
+
+<plain>
+rake
</plain>
h4. Validation
Please validate the generated HTML with:
<plain>
-bundle exec rake validate_guides
+bundle exec rake guides:validate
</plain>
Particularly, titles get an ID generated from their content and this often leads to duplicates. Please set +WARNINGS=1+ when generating guides to detect them. The warning messages suggest a solution.
@@ -85,8 +97,8 @@ h3. Kindle Guides
h4(#generation-kindle). Generation
-To generate guides for the Kindle, you need to provide +KINDLE=1+ as an environment variable:
+To generate guides for the Kindle, use the following rake task:
<plain>
-KINDLE=1 bundle exec rake generate_guides
+bundle exec rake guides:generate:kindle
</plain>

0 comments on commit 669694f

Please sign in to comment.