Merge pull request #6502 from rafmagana/guides_refactor_rakefile
[Guides] refactor rakefile to have a :guides namespace and a task that shows help
This commit is contained in:
commit
669694fe88
@ -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"
|
||||
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:
|
||||
|
||||
#{%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
|
||||
|
||||
# Validate guides -------------------------------------------------------------------------
|
||||
desc 'Validate guides, use ONLY=foo to process just "foo.html"'
|
||||
task :validate_guides do
|
||||
ruby "w3c_validator.rb"
|
||||
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,7 +74,13 @@ 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
|
||||
@ -76,7 +88,7 @@ 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>
|
||||
|
Loading…
Reference in New Issue
Block a user