class Rake::RDocTask

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

external [RW]

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

inline_source [RW]

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]

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| ... }

Source

    # File lib/rake/rdoctask.rb
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

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

Public Instance Methods

before_running_rdoc (&block)

Source

    # File lib/rake/rdoctask.rb
190 def before_running_rdoc(&block)
191   @before_running_rdoc = block
192 end

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.

define ()

Source

    # File lib/rake/rdoctask.rb
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

Create the tasks defined by this task lib.

option_list ()

Source

    # File lib/rake/rdoctask.rb
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

option_string ()

Source

    # File lib/rake/rdoctask.rb
183 def option_string
184   option_list.join(' ')
185 end

quote (str)

Source

    # File lib/rake/rdoctask.rb
175 def quote(str)
176   if @external
177     "'#{str}'"
178   else
179     str
180   end
181 end

Private Instance Methods

clobber_task_name ()

Source

    # File lib/rake/rdoctask.rb
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

rdoc_target ()

Source

    # File lib/rake/rdoctask.rb
196 def rdoc_target
197   "#{rdoc_dir}/index.html"
198 end

rdoc_task_name ()

Source

    # File lib/rake/rdoctask.rb
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

rerdoc_task_name ()

Source

    # File lib/rake/rdoctask.rb
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