class RDoc::Task

RDoc::Task creates the following rake tasks to generate and clean up RDoc output:

rdoc: Main task for this RDoc task.
clobber_rdoc: Delete all the rdoc files. This target is automatically added to the main clobber target.
rerdoc: Rebuild the rdoc files from scratch, even if they are not out of date.

Simple Example:

require 'rdoc/task'

RDoc::Task.new do |rdoc|
  rdoc.main = "README.rdoc"
  rdoc.rdoc_files.include("README.rdoc", "lib/**/*.rb")
end

The rdoc object passed to the block is an RDoc::Task object. See the attributes list for the RDoc::Task class for available customization options.

Specifying different task names¶ ↑

You may wish to give the task a different name, such as if you are generating two sets of documentation. For instance, if you want to have a development set of documentation including private methods:

require 'rdoc/task'

RDoc::Task.new :rdoc_dev do |rdoc|
  rdoc.main = "README.doc"
  rdoc.rdoc_files.include("README.rdoc", "lib/**/*.rb")
  rdoc.options << "--all"
end

The tasks would then be named :rdoc_dev, :clobber_rdoc_dev, and :rerdoc_dev.

If you wish to have completely different task names, then pass a Hash as first argument. With the :rdoc, :clobber_rdoc and :rerdoc options, you can customize the task names to your liking.

For example:

require 'rdoc/task'

RDoc::Task.new(:rdoc => "rdoc", :clobber_rdoc => "rdoc:clean",
               :rerdoc => "rdoc:force")

This will create the tasks :rdoc, :rdoc:clean and :rdoc:force.

Attributes

external[RW]

Whether to run the rdoc process as an external shell (default is false)

generator[RW]

Name of format generator (--format) used by rdoc. (defaults to rdoc's default)

main[RW]

Name of file to be used as the main, top level file of the RDoc. (default is none)

markup[RW]

Comment markup format. rdoc, rd and tomdoc are supported. (default is 'rdoc')

name[RW]

Name of the main, top level task. (default is :rdoc)

options[RW]

Additional list of options to be passed rdoc. (default is [])

rdoc_dir[RW]

Name of directory to receive the html output files. (default is “html”)

rdoc_files[RW]

List of files to be included in the rdoc generation. (default is [])

template[RW]

Name of template to be used by rdoc. (defaults to rdoc's default)

title[RW]

Title of RDoc documentation. (defaults to rdoc's default)

Public Class Methods

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

Create an RDoc task with the given name. See the RDoc::Task class overview for documentation.

# File lib/rdoc/task.rb, line 155
def initialize name = :rdoc # :yield: self
  defaults

  check_names name

  @name = name

  yield self if block_given?

  define
end

Public Instance Methods

before_running_rdoc(&block) click to toggle source

The block passed to this method will be called just before running the RDoc generator. It is allowed to modify RDoc::Task attributes inside the block.

# File lib/rdoc/task.rb, line 273
def before_running_rdoc(&block)
  @before_running_rdoc = block
end

check_names(names) click to toggle source

Ensures that names only includes names for the :rdoc, :clobber_rdoc and :rerdoc. If other names are given an ArgumentError is raised.

# File lib/rdoc/task.rb, line 171
def check_names names
  return unless Hash === names

  invalid_options =
    names.keys.map { |k| k.to_sym } - [:rdoc, :clobber_rdoc, :rerdoc]

  unless invalid_options.empty? then
    raise ArgumentError, "invalid options: #{invalid_options.join ', '}"
  end
end

clobber_task_description() click to toggle source

Task description for the clobber rdoc task or its renamed equivalent

# File lib/rdoc/task.rb, line 185
def clobber_task_description
  "Remove RDoc HTML files"
end

defaults() click to toggle source

Sets default task values

# File lib/rdoc/task.rb, line 192
def defaults
  @name = :rdoc
  @rdoc_files = Rake::FileList.new
  @rdoc_dir = 'html'
  @main = nil
  @title = nil
  @template = nil
  @generator = nil
  @options = []
end

define() click to toggle source

Create the tasks defined by this task lib.

# File lib/rdoc/task.rb, line 221
def define
  desc rdoc_task_description
  task rdoc_task_name

  desc rerdoc_task_description
  task rerdoc_task_name => [clobber_task_name, rdoc_task_name]

  desc clobber_task_description
  task clobber_task_name do
    rm_r @rdoc_dir rescue nil
  end

  task :clobber => [clobber_task_name]

  directory @rdoc_dir

  rdoc_target_deps = [
    @rdoc_files,
    Rake.application.rakefile
  ].flatten.compact

  task rdoc_task_name => [rdoc_target]
  file rdoc_target => rdoc_target_deps do
    @before_running_rdoc.call if @before_running_rdoc
    args = option_list + @rdoc_files

    $stderr.puts "rdoc #{args.join ' '}" if Rake.application.options.trace
    RDoc::RDoc.new.document args
  end

  self
end

option_list() click to toggle source

List of options that will be supplied to RDoc

# File lib/rdoc/task.rb, line 257
def option_list
  result = @options.dup
  result << "-o"       << @rdoc_dir
  result << "--main"   << main      if main
  result << "--markup" << markup    if markup
  result << "--title"  << title     if title
  result << "-T"       << template  if template
  result << '-f'       << generator if generator
  result
end

rdoc_task_description() click to toggle source

Task description for the rdoc task or its renamed equivalent

# File lib/rdoc/task.rb, line 280
def rdoc_task_description
  'Build RDoc HTML files'
end

rerdoc_task_description() click to toggle source

Task description for the rerdoc task or its renamed description

# File lib/rdoc/task.rb, line 287
def rerdoc_task_description
  "Rebuild RDoc HTML files"
end

Private Instance Methods

clobber_task_name() click to toggle source

# File lib/rdoc/task.rb, line 304
def clobber_task_name
  case name
  when Hash then (name[:clobber_rdoc] || "clobber_rdoc").to_s
  else           "clobber_#{name}"
  end
end

rdoc_target() click to toggle source

# File lib/rdoc/task.rb, line 293
def rdoc_target
  "#{rdoc_dir}/created.rid"
end

rdoc_task_name() click to toggle source

# File lib/rdoc/task.rb, line 297
def rdoc_task_name
  case name
  when Hash then (name[:rdoc] || "rdoc").to_s
  else           name.to_s
  end
end

rerdoc_task_name() click to toggle source

# File lib/rdoc/task.rb, line 311
def rerdoc_task_name
  case name
  when Hash then (name[:rerdoc] || "rerdoc").to_s
  else           "re#{name}"
  end
end