class Rake::RDocTask

  1. lib/rake/rdoctask.rb
Parent: Rake

NOTE: Rake::RDocTask is deprecated in favor of RDoc:Task which is included in RDoc 2.4.2+. Use require ‘rdoc/task’ to require it.

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

The rd object passed to the block is an RDocTask object. See the attributes list for the RDocTask 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:

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.

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:

Rake::RDocTask.new(:rdoc => "rdoc", :clobber_rdoc => "rdoc:clean", :rerdoc => "rdoc:force")

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

Attributes

name [RW]

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

rdoc_dir [RW]

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

title [RW]

Title of RDoc documentation. (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)

template [RW]

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

rdoc_files [RW]

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

options [RW]

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

external [RW]

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

inline_source [RW]

Public Class methods

new (name = :rdoc)

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

[show source]
     # File lib/rake/rdoctask.rb, line 108
108:       def initialize(name = :rdoc)  # :yield: self
109:         if name.is_a?(Hash)
110:           invalid_options = name.keys.map { |k| k.to_sym } - [:rdoc, :clobber_rdoc, :rerdoc]
111:           if !invalid_options.empty?
112:             raise ArgumentError, "Invalid option(s) passed to RDocTask.new: #{invalid_options.join(", ")}"
113:           end
114:         end
115: 
116:         @name = name
117:         @rdoc_files = Rake::FileList.new
118:         @rdoc_dir = 'html'
119:         @main = nil
120:         @title = nil
121:         @template = nil
122:         @external = false
123:         @inline_source = true
124:         @options = []
125:         yield self if block_given?
126:         define
127:       end

Public Instance methods

define ()

Create the tasks defined by this task lib.

[show source]
     # File lib/rake/rdoctask.rb, line 130
130:       def define
131:         if rdoc_task_name != "rdoc"
132:           desc "Build the RDOC HTML Files"
133:         else
134:           desc "Build the #{rdoc_task_name} HTML Files"
135:         end
136:         task rdoc_task_name
137: 
138:         desc "Force a rebuild of the RDOC files"
139:         task rerdoc_task_name => [clobber_task_name, rdoc_task_name]
140: 
141:         desc "Remove rdoc products"
142:         task clobber_task_name do
143:           rm_r rdoc_dir rescue nil
144:         end
145: 
146:         task :clobber => [clobber_task_name]
147: 
148:         directory @rdoc_dir
149:         task rdoc_task_name => [rdoc_target]
150:         file rdoc_target => @rdoc_files + [Rake.application.rakefile] do
151:           rm_r @rdoc_dir rescue nil
152:           @before_running_rdoc.call if @before_running_rdoc
153:           args = option_list + @rdoc_files
154:           if @external
155:             argstring = args.join(' ')
156:             sh %{ruby -Ivendor vendor/rd #{argstring}}
157:           else
158:             require 'rdoc/rdoc'
159:             RDoc::RDoc.new.document(args)
160:           end
161:         end
162:         self
163:       end
option_list ()
[show source]
     # File lib/rake/rdoctask.rb, line 165
165:       def option_list
166:         result = @options.dup
167:         result << "-o" << @rdoc_dir
168:         result << "--main" << quote(main) if main
169:         result << "--title" << quote(title) if title
170:         result << "-T" << quote(template) if template
171:         result << "--inline-source" if inline_source && !@options.include?("--inline-source") && !@options.include?("-S")
172:         result
173:       end
quote (str)
[show source]
     # File lib/rake/rdoctask.rb, line 175
175:       def quote(str)
176:         if @external
177:           "'#{str}'"
178:         else
179:           str
180:         end
181:       end
option_string ()
[show source]
     # File lib/rake/rdoctask.rb, line 183
183:       def option_string
184:         option_list.join(' ')
185:       end
before_running_rdoc (&block)

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

[show source]
     # File lib/rake/rdoctask.rb, line 190
190:       def before_running_rdoc(&block)
191:         @before_running_rdoc = block
192:       end

Private Instance methods

rdoc_target ()
[show source]
     # File lib/rake/rdoctask.rb, line 196
196:       def rdoc_target
197:         "#{rdoc_dir}/index.html"
198:       end
rdoc_task_name ()
[show source]
     # File lib/rake/rdoctask.rb, line 200
200:       def rdoc_task_name
201:         case name
202:         when Hash
203:           (name[:rdoc] || "rdoc").to_s
204:         else
205:           name.to_s
206:         end
207:       end
clobber_task_name ()
[show source]
     # File lib/rake/rdoctask.rb, line 209
209:       def clobber_task_name
210:         case name
211:         when Hash
212:           (name[:clobber_rdoc] || "clobber_rdoc").to_s
213:         else
214:           "clobber_#{name}"
215:         end
216:       end
rerdoc_task_name ()
[show source]
     # File lib/rake/rdoctask.rb, line 218
218:       def rerdoc_task_name
219:         case name
220:         when Hash
221:           (name[:rerdoc] || "rerdoc").to_s
222:         else
223:           "re#{name}"
224:         end
225:       end