Class: Rake::RDocTask
Overview
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. << "--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
.
Constant Summary
Constants included from FileUtils
FileUtils::LN_SUPPORTED, FileUtils::RUBY
Instance Attribute Summary collapse
-
#external ⇒ Object
Whether to run the rdoc process as an external shell (default is false).
-
#inline_source ⇒ Object
Returns the value of attribute inline_source.
-
#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.
-
#define ⇒ Object
Create the tasks defined by this task lib.
-
#initialize(name = :rdoc) {|_self| ... } ⇒ RDocTask
constructor
Create an RDoc task with the given name.
- #option_list ⇒ Object
- #option_string ⇒ Object
- #quote(str) ⇒ Object
Methods inherited from TaskLib
Methods included from FileUtilsExt
#nowrite, #rake_check_options, #rake_merge_option, #rake_output_message, #verbose, #when_writing
Methods included from FileUtils
#ruby, #safe_ln, #sh, #split_all
Methods included from Cloneable
Constructor Details
#initialize(name = :rdoc) {|_self| ... } ⇒ RDocTask
Create an RDoc task with the given name. See the RDocTask class overview for documentation.
108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 |
# File 'lib/rake/rdoctask.rb', line 108 def initialize(name = :rdoc) # :yield: self if name.is_a?(Hash) = name.keys.map { |k| k.to_sym } - [:rdoc, :clobber_rdoc, :rerdoc] if !.empty? raise ArgumentError, "Invalid option(s) passed to RDocTask.new: #{.join(", ")}" end end @name = name @rdoc_files = Rake::FileList.new @rdoc_dir = 'html' @main = nil @title = nil @template = nil @external = false @inline_source = true @options = [] 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)
102 103 104 |
# File 'lib/rake/rdoctask.rb', line 102 def external @external end |
#inline_source ⇒ Object
Returns the value of attribute inline_source.
104 105 106 |
# File 'lib/rake/rdoctask.rb', line 104 def inline_source @inline_source end |
#main ⇒ Object
Name of file to be used as the main, top level file of the RDoc. (default is none)
90 91 92 |
# File 'lib/rake/rdoctask.rb', line 90 def main @main end |
#name ⇒ Object
Name of the main, top level task. (default is :rdoc)
80 81 82 |
# File 'lib/rake/rdoctask.rb', line 80 def name @name end |
#options ⇒ Object
Additional list of options to be passed rdoc. (default is [])
99 100 101 |
# File 'lib/rake/rdoctask.rb', line 99 def @options end |
#rdoc_dir ⇒ Object
Name of directory to receive the html output files. (default is “html”)
83 84 85 |
# File 'lib/rake/rdoctask.rb', line 83 def rdoc_dir @rdoc_dir end |
#rdoc_files ⇒ Object
List of files to be included in the rdoc generation. (default is [])
96 97 98 |
# File 'lib/rake/rdoctask.rb', line 96 def rdoc_files @rdoc_files end |
#template ⇒ Object
Name of template to be used by rdoc. (defaults to rdoc’s default)
93 94 95 |
# File 'lib/rake/rdoctask.rb', line 93 def template @template end |
#title ⇒ Object
Title of RDoc documentation. (defaults to rdoc’s default)
86 87 88 |
# File 'lib/rake/rdoctask.rb', line 86 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 RDocTask attributes inside the block.
190 191 192 |
# File 'lib/rake/rdoctask.rb', line 190 def before_running_rdoc(&block) @before_running_rdoc = block end |
#define ⇒ Object
Create the tasks defined by this task lib.
130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 |
# File 'lib/rake/rdoctask.rb', line 130 def define if rdoc_task_name != "rdoc" desc "Build the RDOC HTML Files" else desc "Build the #{rdoc_task_name} HTML Files" end task rdoc_task_name desc "Force a rebuild of the RDOC files" task rerdoc_task_name => [clobber_task_name, rdoc_task_name] desc "Remove rdoc products" task clobber_task_name do rm_r rdoc_dir rescue nil end task :clobber => [clobber_task_name] directory @rdoc_dir task rdoc_task_name => [rdoc_target] file rdoc_target => @rdoc_files + [Rake.application.rakefile] do rm_r @rdoc_dir rescue nil @before_running_rdoc.call if @before_running_rdoc args = option_list + @rdoc_files if @external argstring = args.join(' ') sh %{ruby -Ivendor vendor/rd #{argstring}} else require 'rdoc/rdoc' RDoc::RDoc.new.document(args) end end self end |
#option_list ⇒ Object
165 166 167 168 169 170 171 172 173 |
# File 'lib/rake/rdoctask.rb', line 165 def option_list result = @options.dup result << "-o" << @rdoc_dir result << "--main" << quote(main) if main result << "--title" << quote(title) if title result << "-T" << quote(template) if template result << "--inline-source" if inline_source && !@options.include?("--inline-source") && !@options.include?("-S") result end |
#option_string ⇒ Object
183 184 185 |
# File 'lib/rake/rdoctask.rb', line 183 def option_string option_list.join(' ') end |
#quote(str) ⇒ Object
175 176 177 178 179 180 181 |
# File 'lib/rake/rdoctask.rb', line 175 def quote(str) if @external "'#{str}'" else str end end |