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
2012-05-26 15:29:47 -04:00
ruby " rails_guides.rb "
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 "