2017-08-13 09:02:48 -04:00
# frozen_string_literal: true
2012-05-26 15:29:47 -04:00
namespace :guides do
2012-09-07 00:09:56 -04:00
desc 'Generate guides (for authors), use ONLY=foo to process just "foo.md"'
2016-08-06 13:39:28 -04:00
task generate: "generate:html"
2012-05-26 15:29:47 -04:00
2017-03-09 03:22:33 -05:00
# 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
2012-05-26 15:29:47 -04:00
namespace :generate do
desc "Generate HTML guides"
2017-04-19 20:02:03 -04:00
task html: :encoding do
2015-07-29 20:00:58 -04:00
ENV["WARNINGS"] = "1" # authors can't disable this
2018-02-04 08:37:17 -05:00
ruby "-Eutf-8:utf-8", "rails_guides.rb"
2012-05-26 15:29:47 -04:00
end
2015-02-28 20:39:52 -05:00
desc "Generate .mobi file. The kindlegen executable must be in your PATH. You can get it for free from http://www.amazon.com/gp/feature.html?docId=1000765211"
2017-04-19 20:02:03 -04:00
task kindle: :encoding do
2016-12-28 21:53:51 -05:00
require "kindlerb"
2016-12-18 10:13:50 -05:00
unless Kindlerb.kindlegen_available?
abort "Please run `setupkindlerb` to install kindlegen"
2012-11-28 11:25:32 -05:00
end
2016-08-06 13:55:02 -04:00
unless `convert` =~ /convert/
2017-02-12 04:21:20 -05:00
abort "Please install ImageMagick"
2012-11-28 11:25:32 -05:00
end
2016-08-06 13:21:59 -04:00
ENV["KINDLE"] = "1"
Rake::Task["guides:generate:html"].invoke
2012-05-26 15:29:47 -04:00
end
end
# Validate guides -------------------------------------------------------------------------
desc 'Validate guides, use ONLY=foo to process just "foo.html"'
2017-04-19 20:02:03 -04:00
task validate: :encoding do
2012-05-26 15:29:47 -04:00
ruby "w3c_validator.rb"
end
2012-03-17 11:32:49 -04:00
2012-05-26 16:05:52 -04:00
desc "Show help"
task :help do
2017-02-12 04:21:20 -05:00
puts <<HELP
2012-05-26 16:05:52 -04:00
2014-11-25 19:54:30 -05:00
Guides are taken from the source directory, and the result goes into the
2012-05-26 16:05:52 -04:00
output directory. Assets are stored under files, and copied to output/files as
part of the generation process.
2014-11-25 19:54:30 -05:00
You can generate HTML, Kindle or both formats using the `guides:generate` task.
2014-12-05 10:32:50 -05:00
All of these processes are handled via rake tasks, here's a full list of them:
2012-05-28 17:17:00 -04:00
#{%x[rake -T]}
2012-05-26 16:05:52 -04:00
Some arguments may be passed via environment variables:
2017-02-12 04:21:20 -05:00
RAILS_VERSION=tag
If guides are being generated for a specific Rails version set the Git tag
here, otherwise the current SHA1 is going to be used to generate edge guides.
2012-05-26 16:05:52 -04:00
ALL=1
Force generation of all guides.
ONLY=name
Useful if you want to generate only one or a set of guides.
2012-08-31 12:01:06 -04:00
2012-05-26 16:05:52 -04:00
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)
Examples:
2017-02-12 04:21:20 -05:00
$ rake guides:generate ALL=1 RAILS_VERSION=v5.1.0
$ rake guides:generate ONLY=migrations
$ rake guides:generate:kindle
2012-05-26 16:05:52 -04:00
$ rake guides:generate GUIDES_LANGUAGE=es
2017-02-12 04:21:20 -05:00
HELP
2012-05-26 16:05:52 -04:00
end
2012-03-17 11:32:49 -04:00
end
2012-05-26 16:05:52 -04:00
2016-08-06 13:39:28 -04:00
task default: "guides:help"