RDoc::Task creates the following rake tasks to generate and clean up RDoc output:
- rdoc
-
Main task for this
RDoctask. - 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.
Name of the main, top level task. (default is :rdoc)
Comment markup format. rdoc, rd and tomdoc are supported. (default is ‘rdoc’)
Name of directory to receive the html output files. (default is “html”)
Name of file to be used as the main, top level file of the RDoc. (default is none)
Name of template to be used by rdoc. (defaults to rdoc’s default)
Name of format generator (--format) used by rdoc. (defaults to rdoc’s default)
List of files to be included in the rdoc generation. (default is [])
Additional list of options to be passed rdoc. (default is [])
Whether to run the rdoc process as an external shell (default is false)
# File tmp/rubies/ruby-2.7.6/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
Create an RDoc task with the given name. See the RDoc::Task class overview for documentation.
# File tmp/rubies/ruby-2.7.6/lib/rdoc/task.rb, line 273
def before_running_rdoc(&block)
@before_running_rdoc = block
end
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 tmp/rubies/ruby-2.7.6/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
Ensures that names only includes names for the :rdoc, :clobber_rdoc and :rerdoc. If other names are given an ArgumentError is raised.
# File tmp/rubies/ruby-2.7.6/lib/rdoc/task.rb, line 185
def clobber_task_description
"Remove RDoc HTML files"
end
Task description for the clobber rdoc task or its renamed equivalent
# File tmp/rubies/ruby-2.7.6/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
# File tmp/rubies/ruby-2.7.6/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
Sets default task values
# File tmp/rubies/ruby-2.7.6/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
Create the tasks defined by this task lib.
# File tmp/rubies/ruby-2.7.6/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
List of options that will be supplied to RDoc
# File tmp/rubies/ruby-2.7.6/lib/rdoc/task.rb, line 293
def rdoc_target
"#{rdoc_dir}/created.rid"
end
# File tmp/rubies/ruby-2.7.6/lib/rdoc/task.rb, line 280
def rdoc_task_description
'Build RDoc HTML files'
end
Task description for the rdoc task or its renamed equivalent
# File tmp/rubies/ruby-2.7.6/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
# File tmp/rubies/ruby-2.7.6/lib/rdoc/task.rb, line 287
def rerdoc_task_description
"Rebuild RDoc HTML files"
end
Task description for the rerdoc task or its renamed description
# File tmp/rubies/ruby-2.7.6/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