1 # frozen_string_literal: true
3 # Copyright (c) 2003, 2004 Jim Weirich, 2009 Eric Hodel
5 # Permission is hereby granted, free of charge, to any person obtaining
6 # a copy of this software and associated documentation files (the
7 # "Software"), to deal in the Software without restriction, including
8 # without limitation the rights to use, copy, modify, merge, publish,
9 # distribute, sublicense, and/or sell copies of the Software, and to
10 # permit persons to whom the Software is furnished to do so, subject to
11 # the following conditions:
13 # The above copyright notice and this permission notice shall be
14 # included in all copies or substantial portions of the Software.
16 # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
17 # EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
18 # MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
19 # NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
20 # LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
21 # OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
22 # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
28 end unless defined?(RDoc)
33 end unless defined?(Rake)
35 require_relative '../rdoc'
37 require 'rake/tasklib'
40 # RDoc::Task creates the following rake tasks to generate and clean up RDoc
44 # Main task for this RDoc task.
47 # Delete all the rdoc files. This target is automatically added to the main
51 # Rebuild the rdoc files from scratch, even if they are not out of date.
54 # Print RDoc coverage report for all rdoc files.
60 # RDoc::Task.new do |rdoc|
61 # rdoc.main = "README.rdoc"
62 # rdoc.rdoc_files.include("README.rdoc", "lib/**/*.rb")
65 # The +rdoc+ object passed to the block is an RDoc::Task object. See the
66 # attributes list for the RDoc::Task class for available customization options.
68 # == Specifying different task names
70 # You may wish to give the task a different name, such as if you are
71 # generating two sets of documentation. For instance, if you want to have a
72 # development set of documentation including private methods:
76 # RDoc::Task.new :rdoc_dev do |rdoc|
77 # rdoc.main = "README.rdoc"
78 # rdoc.rdoc_files.include("README.rdoc", "lib/**/*.rb")
79 # rdoc.options << "--all"
82 # The tasks would then be named :<em>rdoc_dev</em>,
83 # :clobber_<em>rdoc_dev</em>, and :re<em>rdoc_dev</em>.
85 # If you wish to have completely different task names, then pass a Hash as
86 # first argument. With the <tt>:rdoc</tt>, <tt>:clobber_rdoc</tt> and
87 # <tt>:rerdoc</tt> options, you can customize the task names to your liking.
93 # RDoc::Task.new(:rdoc => "rdoc", :clobber_rdoc => "rdoc:clean",
94 # :rerdoc => "rdoc:force")
96 # This will create the tasks <tt>:rdoc</tt>, <tt>:rdoc:clean</tt>,
97 # <tt>:rdoc:force</tt>, and <tt>:rdoc:coverage</tt>.
99 class RDoc::Task < Rake::TaskLib
102 # Name of the main, top level task. (default is :rdoc)
107 # Comment markup format. rdoc, rd and tomdoc are supported. (default is
110 attr_accessor :markup
113 # Name of directory to receive the html output files. (default is "html")
115 attr_accessor :rdoc_dir
118 # Title of RDoc documentation. (defaults to rdoc's default)
123 # Name of file to be used as the main, top level file of the RDoc. (default
129 # Name of template to be used by rdoc. (defaults to rdoc's default)
131 attr_accessor :template
134 # Name of format generator (<tt>--format</tt>) used by rdoc. (defaults to
137 attr_accessor :generator
140 # List of files to be included in the rdoc generation. (default is [])
142 attr_accessor :rdoc_files
145 # Additional list of options to be passed rdoc. (default is [])
147 attr_accessor :options
150 # Whether to run the rdoc process as an external shell (default is false)
152 attr_accessor :external
155 # Create an RDoc task with the given name. See the RDoc::Task class overview
158 def initialize name = :rdoc # :yield: self
165 yield self if block_given?
171 # Ensures that +names+ only includes names for the :rdoc, :clobber_rdoc and
172 # :rerdoc. If other names are given an ArgumentError is raised.
174 def check_names names
175 return unless Hash === names
178 names.keys.map { |k| k.to_sym } - [:rdoc, :clobber_rdoc, :rerdoc]
180 unless invalid_options.empty? then
181 raise ArgumentError, "invalid options: #{invalid_options.join ', '}"
186 # Task description for the clobber rdoc task or its renamed equivalent
188 def clobber_task_description
189 "Remove RDoc HTML files"
193 # Sets default task values
197 @rdoc_files = Rake::FileList.new
207 # All source is inline now. This method is deprecated
209 def inline_source # :nodoc:
210 warn "RDoc::Task#inline_source is deprecated"
215 # All source is inline now. This method is deprecated
217 def inline_source=(value) # :nodoc:
218 warn "RDoc::Task#inline_source is deprecated"
222 # Create the tasks defined by this task lib.
225 desc rdoc_task_description
228 desc rerdoc_task_description
229 task rerdoc_task_name => [clobber_task_name, rdoc_task_name]
231 desc clobber_task_description
232 task clobber_task_name do
233 rm_r @rdoc_dir rescue nil
236 task :clobber => [clobber_task_name]
242 Rake.application.rakefile
245 task rdoc_task_name => [rdoc_target]
246 file rdoc_target => rdoc_target_deps do
247 @before_running_rdoc.call if @before_running_rdoc
248 args = option_list + @rdoc_files
250 $stderr.puts "rdoc #{args.join ' '}" if Rake.application.options.trace
251 RDoc::RDoc.new.document args
254 namespace rdoc_task_name do
255 desc coverage_task_description
256 task coverage_task_name do
257 @before_running_rdoc.call if @before_running_rdoc
258 opts = option_list << "-C"
259 args = opts + @rdoc_files
261 $stderr.puts "rdoc #{args.join ' '}" if Rake.application.options.trace
262 RDoc::RDoc.new.document args
270 # List of options that will be supplied to RDoc
273 result = @options.dup
274 result << "-o" << @rdoc_dir
275 result << "--main" << main if main
276 result << "--markup" << markup if markup
277 result << "--title" << title if title
278 result << "-T" << template if template
279 result << '-f' << generator if generator
284 # The block passed to this method will be called just before running the
285 # RDoc generator. It is allowed to modify RDoc::Task attributes inside the
288 def before_running_rdoc(&block)
289 @before_running_rdoc = block
293 # Task description for the rdoc task or its renamed equivalent
295 def rdoc_task_description
296 'Build RDoc HTML files'
300 # Task description for the rerdoc task or its renamed description
302 def rerdoc_task_description
303 "Rebuild RDoc HTML files"
307 # Task description for the coverage task or its renamed description
309 def coverage_task_description
310 "Print RDoc coverage report"
316 "#{rdoc_dir}/created.rid"
321 when Hash then (name[:rdoc] || "rdoc").to_s
326 def clobber_task_name
328 when Hash then (name[:clobber_rdoc] || "clobber_rdoc").to_s
329 else "clobber_#{name}"
335 when Hash then (name[:rerdoc] || "rerdoc").to_s
340 def coverage_task_name
350 # For backwards compatibility
352 RDocTask = RDoc::Task # :nodoc: