namespace :guides do
desc 'Generate guides (for authors), use ONLY=foo to process just "foo.md"' task :generate => 'generate:html' # Guides are written in UTF-8, but the environment may be configured for some # other locale, these tasks are responsible for ensuring the default external # encoding is UTF-8. # # Real use cases: Generation was reported to fail on a machine configured with # GBK (Chinese). The docs server once got misconfigured somehow and had "C", # which broke generation too. task :encoding do %w(LANG LANGUAGE LC_ALL).each do |env_var| ENV[env_var] = "en_US.UTF-8" end end namespace :generate do desc "Generate HTML guides" task :html => :encoding 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 => :encoding do unless `kindlerb -v 2> /dev/null` =~ /kindlerb 0.1.1/ abort "Please `gem install kindlerb` and make sure you have `kindlegen` in your PATH" end unless `convert` =~ /convert/ abort "Please install ImageMagick`" end 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 => :encoding do ruby "w3c_validator.rb" end desc "Show help" task :help do puts <<-help
Guides are taken from the source directory, and the result goes into the output directory. Assets are stored under files, and copied to output/files as part of the generation process.
You can generate HTML, Kindle or both formats using the `guides:generate` task.
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
task :default => 'guides:help'