Class: RDoc::Task
- Inherits:
-
Rake::TaskLib
- Object
- Rake::TaskLib
- RDoc::Task
- Defined in:
- lib/rdoc/task.rb
Overview
RDoc::Task creates the following rake tasks to generate and clean up RDoc output:
- 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:
gem 'rdoc'
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:
gem 'rdoc'
require 'rdoc/task'
RDoc::Task.new :rdoc_dev do |rdoc|
rdoc.main = "README.doc"
rdoc.rdoc_files.include("README.rdoc", "lib/**/*.rb")
rdoc. << "--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:
gem 'rdoc'
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
.
Instance Attribute Summary collapse
-
#external ⇒ Object
Whether to run the rdoc process as an external shell (default is false).
-
#generator ⇒ Object
Name of format generator (--fmt) used by rdoc.
-
#main ⇒ Object
Name of file to be used as the main, top level file of the RDoc.
-
#name ⇒ Object
Name of the main, top level task.
-
#options ⇒ Object
Additional list of options to be passed rdoc.
-
#rdoc_dir ⇒ Object
Name of directory to receive the html output files.
-
#rdoc_files ⇒ Object
List of files to be included in the rdoc generation.
-
#template ⇒ Object
Name of template to be used by rdoc.
-
#title ⇒ Object
Title of RDoc documentation.
Instance Method Summary collapse
-
#before_running_rdoc(&block) ⇒ Object
The block passed to this method will be called just before running the RDoc generator.
-
#check_names(names) ⇒ Object
Ensures that
names
only includes names for the :rdoc, :clobber_rdoc and :rerdoc. -
#clobber_task_description ⇒ Object
Task description for the clobber rdoc task or its renamed equivalent.
-
#defaults ⇒ Object
Sets default task values.
-
#define ⇒ Object
Create the tasks defined by this task lib.
-
#initialize(name = :rdoc) {|_self| ... } ⇒ Task
constructor
Create an RDoc task with the given name.
-
#inline_source ⇒ Object
All source is inline now.
-
#inline_source=(value) ⇒ Object
All source is inline now.
-
#option_list ⇒ Object
List of options that will be supplied to RDoc.
-
#rdoc_task_description ⇒ Object
Task description for the rdoc task or its renamed equivalent.
-
#rerdoc_task_description ⇒ Object
Task description for the rerdoc task or its renamed description.
Constructor Details
#initialize(name = :rdoc) {|_self| ... } ⇒ Task
Create an RDoc task with the given name. See the RDoc::Task class overview for documentation.
151 152 153 154 155 156 157 158 159 160 161 |
# File 'lib/rdoc/task.rb', line 151 def initialize name = :rdoc # :yield: self defaults check_names name @name = name yield self if block_given? define end |
Instance Attribute Details
#external ⇒ Object
Whether to run the rdoc process as an external shell (default is false)
145 146 147 |
# File 'lib/rdoc/task.rb', line 145 def external @external end |
#generator ⇒ Object
Name of format generator (--fmt) used by rdoc. (defaults to rdoc's default)
130 131 132 |
# File 'lib/rdoc/task.rb', line 130 def generator @generator end |
#main ⇒ Object
Name of file to be used as the main, top level file of the RDoc. (default is none)
120 121 122 |
# File 'lib/rdoc/task.rb', line 120 def main @main end |
#name ⇒ Object
Name of the main, top level task. (default is :rdoc)
104 105 106 |
# File 'lib/rdoc/task.rb', line 104 def name @name end |
#options ⇒ Object
Additional list of options to be passed rdoc. (default is [])
140 141 142 |
# File 'lib/rdoc/task.rb', line 140 def @options end |
#rdoc_dir ⇒ Object
Name of directory to receive the html output files. (default is "html")
109 110 111 |
# File 'lib/rdoc/task.rb', line 109 def rdoc_dir @rdoc_dir end |
#rdoc_files ⇒ Object
List of files to be included in the rdoc generation. (default is [])
135 136 137 |
# File 'lib/rdoc/task.rb', line 135 def rdoc_files @rdoc_files end |
#template ⇒ Object
Name of template to be used by rdoc. (defaults to rdoc's default)
125 126 127 |
# File 'lib/rdoc/task.rb', line 125 def template @template end |
#title ⇒ Object
Title of RDoc documentation. (defaults to rdoc's default)
114 115 116 |
# File 'lib/rdoc/task.rb', line 114 def title @title end |
Instance Method Details
#before_running_rdoc(&block) ⇒ Object
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.
269 270 271 |
# File 'lib/rdoc/task.rb', line 269 def before_running_rdoc(&block) @before_running_rdoc = block end |
#check_names(names) ⇒ Object
Ensures that names
only includes names for the :rdoc, :clobber_rdoc and :rerdoc. If other names are given an ArgumentError is raised.
167 168 169 170 171 172 173 174 175 176 |
# File 'lib/rdoc/task.rb', line 167 def check_names names return unless Hash === names = names.keys.map { |k| k.to_sym } - [:rdoc, :clobber_rdoc, :rerdoc] unless .empty? then raise ArgumentError, "invalid options: #{.join ', '}" end end |
#clobber_task_description ⇒ Object
Task description for the clobber rdoc task or its renamed equivalent
181 182 183 |
# File 'lib/rdoc/task.rb', line 181 def clobber_task_description "Remove RDoc HTML files" end |
#defaults ⇒ Object
Sets default task values
188 189 190 191 192 193 194 195 196 197 |
# File 'lib/rdoc/task.rb', line 188 def defaults @name = :rdoc @rdoc_files = Rake::FileList.new @rdoc_dir = 'html' @main = nil @title = nil @template = nil @generator = nil @options = [] end |
#define ⇒ Object
Create the tasks defined by this task lib.
217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 |
# File 'lib/rdoc/task.rb', line 217 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..trace require 'rdoc/rdoc' RDoc::RDoc.new.document args end self end |
#inline_source ⇒ Object
All source is inline now. This method is deprecated
202 203 204 205 |
# File 'lib/rdoc/task.rb', line 202 def inline_source # :nodoc: warn "RDoc::Task#inline_source is deprecated" true end |
#inline_source=(value) ⇒ Object
All source is inline now. This method is deprecated
210 211 212 |
# File 'lib/rdoc/task.rb', line 210 def inline_source=(value) # :nodoc: warn "RDoc::Task#inline_source is deprecated" end |
#option_list ⇒ Object
List of options that will be supplied to RDoc
254 255 256 257 258 259 260 261 262 |
# File 'lib/rdoc/task.rb', line 254 def option_list result = @options.dup result << "-o" << @rdoc_dir result << "--main" << main if main result << "--title" << title if title result << "-T" << template if template result << '-f' << generator if generator result end |
#rdoc_task_description ⇒ Object
Task description for the rdoc task or its renamed equivalent
276 277 278 |
# File 'lib/rdoc/task.rb', line 276 def rdoc_task_description 'Build RDoc HTML files' end |
#rerdoc_task_description ⇒ Object
Task description for the rerdoc task or its renamed description
283 284 285 |
# File 'lib/rdoc/task.rb', line 283 def rerdoc_task_description "Rebuild RDoc HTML files" end |