Class | Rake::RDocTask
In: | lib/rake/rdoctask.rb
Parent: | TaskLib

Create a documentation task that will generate the RDoc files for a project.

The RDocTask will create the following targets:

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:

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

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:

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

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

### Methods

define new option_list option_string quote

### Attributes

external | [RW] | Run the rdoc process as an external shell (default is false)
main | [RW] | Name of file to be used as the main, top level file of the RDoc. (default is none)
name | [RW] | Name of the main, top level task. (default is :rdoc)
options | [RW] | 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. (default is none)

### Public Class methods

new(name=:rdoc) {|self| ...}

Create an RDoc task named rdoc. Default task name is `rdoc`.

[Source]

        # File lib/rake/rdoctask.rb, line 71
    71:     def initialize(name=:rdoc)  # :yield: self
    72:       @name = name
    73:       @rdoc_files = Rake::FileList.new
    74:       @rdoc_dir = 'html'
    75:       @main = nil
    76:       @title = nil
    77:       @template = nil
    78:       @external = false
    79:       @options = []
    80:       yield self if block_given?
    81:       define
    82:     end

### Public Instance methods

define()

Create the tasks defined by this task lib.

[Source]

         # File lib/rake/rdoctask.rb, line 85
     85:     def define
     86:       if name.to_s != "rdoc"
     87:         desc "Build the RDOC HTML Files"
     88:       end
     89:
     90:       desc "Build the #{name} HTML Files"
     91:       task name
     92:
     93:       desc "Force a rebuild of the RDOC files"
     94:       task "re#{name}" => ["clobber_#{name}", name]
     95:
     96:       desc "Remove rdoc products"
     97:       task "clobber_#{name}" do
     98:         rm_r rdoc_dir rescue nil
     99:       end
    100:
    101:       task :clobber => ["clobber_#{name}"]
    102:
    103:       directory @rdoc_dir
    104:       task name => [rdoc_target]
    105:       file rdoc_target => @rdoc_files + [Rake.application.rakefile] do
    106:         rm_r @rdoc_dir rescue nil
    107:         args = option_list + @rdoc_files
    108:         if @external
    109:           argstring = args.join(' ')
    110:           sh %{ruby -Ivendor vender/rd #{argstring}}
    111:         else
    112:           require 'rdoc/rdoc'
    113:           RDoc::RDoc.new.document(args)
    114:         end
    115:       end
    116:       self
    117:     end

option_list()

[Source]

         # File lib/rake/rdoctask.rb, line 119
    119:     def option_list
    120:       result = @options.dup
    121:       result << "-o" << @rdoc_dir
    122:       result << "--main" << quote(main) if main
    123:       result << "--title" << quote(title) if title
    124:       result << "-T" << quote(template) if template
    125:       result
    126:     end

option_string()

[Source]

         # File lib/rake/rdoctask.rb, line 136
    136:     def option_string
    137:       option_list.join(' ')
    138:     end

quote(str)

[Source]

         # File lib/rake/rdoctask.rb, line 128
    128:     def quote(str)
    129:       if @external
    130:         "'#{str}'"
    131:       else
    132:         str
    133:       end
    134:     end

[Validate]