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

default_output_dir[RW]

Base directories used by the task.

ext_mappings[R]

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.

layout_dir[RW]

Base directories used by the task.

monitor_interval[RW]

The approximate number of seconds between update checks when running monitor mode (Default: 1)

name[R]

The base-name for tasks created by this instance, supplied at instantiation.

output_dir[RW]

Base directories used by the task.

output_dir=[RW]

Base directories used by the task.

pages[R]

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.

res[R]

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.

show_file_tasks[RW]

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.

show_file_tasks=[RW]

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.

show_file_tasks?[RW]

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.

show_page_tasks=[RW]

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.

show_page_tasks?[RW]

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

new(name = :doc) { |self| ... } click to toggle source

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

ext_mapping(match, extension, output_dir = self.default_output_dir, &block) click to toggle source

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

define() click to toggle source
    # File lib/rote/rotetasks.rb
206 def define
207   define_res_tasks
208   define_page_tasks
209   define_main_tasks
210   nil
211 end
define_main_tasks() click to toggle source
    # 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_page_tasks() click to toggle source

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_res_tasks() click to toggle source

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
target_fn(dir_rx, fn) click to toggle source

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