class Rote::DocTask
Rake
task library that provides a set of tasks to transform documentation using Rote
. To use, create a new instance of this class in your Rakefile, performing appropriate configuration in a block supplied to new
. This will automatically register a set of tasks with names based on the name you supply. The tasks defined are:
#{name} - Transform all documentation, copy resources. #{name}_pages - Transform all pages #{name}_res - Copy resources #{name}_monitor - Start watching for changes #clobber_{name} - Remove output
Constants
- DEFAULT_SRC_EXCLUDES
Default exclusion patterns for the page sources. These are applied along with the defaults from
FileList
.
Attributes
Base directories used by the task.
Ordered ExtHash
that supplies mappings between input and output file extensions. Keys are regexps that are matched in order against the search key.
The values are [extension, ({ |page| …}), out_dir] . If a mapping has a block, it is executed when pages with a matching extension are, instantiated (before common and page code). It can be used to apply filters, for example, on a per-extension basis.
Base directories used by the task.
The approximate number of seconds between update checks when running monitor mode (Default: 1)
The base-name for tasks created by this instance, supplied at instantiation.
Base directories used by the task.
Base directories used by the task.
Globs for the FileList
that supplies the pages to transform. You should configure the pages_dir
and include
at least one entry here. (you may add exclude
strings or regexps, too). Patterns added are made relative to the pages_dir
and added to a FileList once init is complete.
Globs for the FileList
that supplies the resources to copy. You should configure the layout_dir
and include
at least one entry here (you may add exclude
strings or regexps, too).
This is not a FileList
- the patterns supplied to this are used with the base-directory specified to construct an appropriate FileList
.
If show_page_tasks
is true
, then the file tasks created for each output file will be shown in the Rake
task listing from the command line.
If show_page_tasks
is true
, then the file tasks created for each output file will be shown in the Rake
task listing from the command line.
If show_page_tasks
is true
, then the file tasks created for each output file will be shown in the Rake
task listing from the command line.
If show_page_tasks
is true
, then the file tasks created for each output file will be shown in the Rake
task listing from the command line.
If show_page_tasks
is true
, then the file tasks created for each output file will be shown in the Rake
task listing from the command line.
Public Class Methods
Create a new DocTask
, using the supplied block for configuration, and define tasks with the specified base-name within Rake
.
# File lib/rote/rotetasks.rb 188 def initialize(name = :doc) # :yield: self if block_given? 189 @name = name 190 @output_dir = '.' 191 @pages = FilePatterns.new('.') 192 @res = FilePatterns.new('.') 193 @monitor_interval = 1 194 @ext_mappings = ExtHash.new 195 @show_page_tasks = false 196 197 DEFAULT_SRC_EXCLUDES.each { |excl| @pages.exclude(excl) } 198 199 yield self if block_given? 200 201 define 202 end
Public Instance Methods
Define an extension mapping for the specified regex, which will be replaced with the specified extension. If a block is supplied it will be called with each matching Page
as it’s created.
Extension mappings also allow the output directory to be specified on a per-extension basis. If no output directory is specified, the default output directory is used.
# File lib/rote/rotetasks.rb 168 def ext_mapping(match, extension, output_dir = self.default_output_dir, &block) 169 @ext_mappings[match] = [extension,block,output_dir] 170 end
Private Instance Methods
# File lib/rote/rotetasks.rb 206 def define 207 define_res_tasks 208 define_page_tasks 209 define_main_tasks 210 nil 211 end
# File lib/rote/rotetasks.rb 297 def define_main_tasks 298 desc "Build the documentation" 299 task name => ["#{name}_pages", "#{name}_res"] 300 301 task :clobber => [ "clobber_#{name}" ] 302 desc "Remove the generated documentation" 303 task "clobber_#{name}" do 304 rm_rf output_dir 305 end 306 307 # thanks to Jonathan Paisley for this :) 308 # Relies on Rake mods made below. 309 desc "Monitor and automatically rebuild the documentation" 310 task "#{name}_monitor" do 311 loop do 312 Rake::Task::tasks.each { |t| t.reset } 313 Rake::Task[name].invoke 314 if Rake::Task::tasks.grep(Rake::FileTask).detect { |t| t.executed? } then 315 Rake::Task["#{name}_refresh"].invoke if Rake::Task.task_defined?("#{name}_refresh") 316 end 317 sleep monitor_interval 318 end 319 end 320 321 end
define a task for each page, and ‘all pages’ task
# File lib/rote/rotetasks.rb 247 def define_page_tasks 248 pages_fl = pages.to_filelist 249 250 gen_files = pages_fl.select { |fn| not File.directory?(fn) }.map do |fn| 251 tfn, blk = target_fn(/^#{pages.dir}/, fn) 252 253 desc "#{fn} => #{tfn}" if show_file_tasks? 254 file tfn => [fn] do 255 dn = File.dirname(tfn) 256 mkdir_p dn unless File.exists?(dn) 257 puts "tr #{fn} => #{tfn}" 258 begin 259 File.open(tfn, 'w+') do |f| 260 # new page, run extension block, render out, throw away 261 f << Page.new(fn,pages.dir,layout_dir,&blk).render 262 end 263 rescue => e 264 # Oops... Unlink file and dump backtrace 265 File.unlink(tfn) 266 bt = e.backtrace 267 end_idx = bt.each_with_index do |entry, idx| 268 break idx if entry =~ /^#{File.dirname(__FILE__)}/ 269 end 270 puts bt[0...end_idx] 271 raise 272 end 273 end 274 275 # Each page depends properly on source and common - thx again 276 # Jonathan :) 277 src_rb = Page::page_ruby_filename(fn) 278 if File.exists?(src_rb) 279 file tfn => [src_rb] 280 end 281 282 common_rbs = Page::resolve_common_rubys(File.dirname(fn)) 283 file tfn => common_rbs unless common_rbs.empty? 284 285 tfn 286 end 287 288 desc "Render new/changed documentation pages" 289 task "#{name}_pages" => gen_files 290 task "clobber_#{name}_pages" do 291 gen_files.each do |f| 292 rm_f f 293 end 294 end 295 end
define a task for each resource, and ‘all resources’ task
# File lib/rote/rotetasks.rb 228 def define_res_tasks 229 res_fl = res.to_filelist 230 tasks = res_fl.select { |fn| not File.directory?(fn) }.map do |fn| 231 tfn, = target_fn(/^#{res.dir}/, fn) 232 233 desc "#{fn} => #{tfn}" if show_file_tasks? 234 file tfn => [fn] do 235 dn = File.dirname(tfn) 236 mkdir_p dn unless File.exists?(dn) 237 cp fn, tfn, :preserve => true 238 end 239 tfn 240 end 241 242 desc "Copy new/changed resources" 243 task "#{name}_res" => tasks 244 end
Get a target filename for a source filename. The dir_rx must match the portion of the directory that will be replaced with the target directory. The extension is mapped through ext_mappings. If a block is configured for this extension, it is returned too.
Returns [target_fn, ({ |page| …})]
# File lib/rote/rotetasks.rb 220 def target_fn(dir_rx, fn) 221 ext = File.extname(fn).sub(/^\./,'') # strip leading dot 222 new_ext, blk, output_dir = ext_mappings[ext] || [ext,nil,self.default_output_dir] 223 tfn = fn.sub(dir_rx, output_dir) 224 [tfn.sub(/#{ext}$/,new_ext),blk] 225 end