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.
[RW] | external | Whether to run the rdoc process as an external shell (default is false) |
[RW] | inline_source | |
[RW] | main | Name of file to be used as the main, top level file of the RDoc. (default is none) |
[RW] | name | Name of the main, top level task. (default is :rdoc) |
[RW] | options | Additional list of options to be passed rdoc. (default is []) |
[RW] | rdoc_dir | Name of directory to receive the html output files. (default is "html") |
[RW] | rdoc_files | List of files to be included in the rdoc generation. (default is []) |
[RW] | template | Name of template to be used by rdoc. (defaults to rdoc‘s default) |
[RW] | title | Title of RDoc documentation. (defaults to rdoc‘s default) |
Create an RDoc task with the given name. See the RDocTask class overview for documentation.
[ show source ]
# File lib/rake/rdoctask.rb, line 89 89: def initialize(name = :rdoc) # :yield: self 90: if name.is_a?(Hash) 91: invalid_options = name.keys.map { |k| k.to_sym } - [:rdoc, :clobber_rdoc, :rerdoc] 92: if !invalid_options.empty? 93: raise ArgumentError, "Invalid option(s) passed to RDocTask.new: #{invalid_options.join(", ")}" 94: end 95: end 96: 97: @name = name 98: @rdoc_files = Rake::FileList.new 99: @rdoc_dir = 'html' 100: @main = nil 101: @title = nil 102: @template = nil 103: @external = false 104: @inline_source = true 105: @options = [] 106: yield self if block_given? 107: define 108: 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.
[ show source ]
# File lib/rake/rdoctask.rb, line 171 171: def before_running_rdoc(&block) 172: @before_running_rdoc = block 173: end
Create the tasks defined by this task lib.
[ show source ]
# File lib/rake/rdoctask.rb, line 111 111: def define 112: if rdoc_task_name != "rdoc" 113: desc "Build the RDOC HTML Files" 114: else 115: desc "Build the #{rdoc_task_name} HTML Files" 116: end 117: task rdoc_task_name 118: 119: desc "Force a rebuild of the RDOC files" 120: task rerdoc_task_name => [clobber_task_name, rdoc_task_name] 121: 122: desc "Remove rdoc products" 123: task clobber_task_name do 124: rm_r rdoc_dir rescue nil 125: end 126: 127: task :clobber => [clobber_task_name] 128: 129: directory @rdoc_dir 130: task rdoc_task_name => [rdoc_target] 131: file rdoc_target => @rdoc_files + [Rake.application.rakefile] do 132: rm_r @rdoc_dir rescue nil 133: @before_running_rdoc.call if @before_running_rdoc 134: args = option_list + @rdoc_files 135: if @external 136: argstring = args.join(' ') 137: sh %{ruby -Ivendor vender/rd #{argstring}} 138: else 139: require 'rdoc/rdoc' 140: RDoc::RDoc.new.document(args) 141: end 142: end 143: self 144: end
[ show source ]
# File lib/rake/rdoctask.rb, line 146 146: def option_list 147: result = @options.dup 148: result << "-o" << @rdoc_dir 149: result << "--main" << quote(main) if main 150: result << "--title" << quote(title) if title 151: result << "-T" << quote(template) if template 152: result << "--inline-source" if inline_source && !@options.include?("--inline-source") && !@options.include?("-S") 153: result 154: end
[ show source ]
# File lib/rake/rdoctask.rb, line 164 164: def option_string 165: option_list.join(' ') 166: end
[ show source ]
# File lib/rake/rdoctask.rb, line 156 156: def quote(str) 157: if @external 158: "'#{str}'" 159: else 160: str 161: end 162: end