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

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

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

[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

[Source]

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

[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]