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
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.
[RW] |
external |
Run the rdoc process as an external shell (default is false)
|
[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 |
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. (default is ‘html’)
|
[RW] |
title |
Title of RDoc documentation. (default is none)
|
Create an RDoc task named rdoc. Default
task name is rdoc.
71: def initialize(name=:rdoc)
72: @name = name
73: @rdoc_files = Rake::FileList.new
74: @rdoc_dir = 'html'
75: @main = nil
76: @title = nil
77: @template = 'html'
78: @external = false
79: @options = []
80: yield self if block_given?
81: define
82: end
Create the tasks defined by this task lib.
85: def define
86: if name.to_s != "rdoc"
87: desc "Build the RDOC HTML Files"
88: end
89:
90: desc "Build the #{name} HTML Files"
91: task name
92:
93: desc "Force a rebuild of the RDOC files"
94: task paste("re", name) => [paste("clobber_", name), name]
95:
96: desc "Remove rdoc products"
97: task paste("clobber_", name) do
98: rm_r rdoc_dir rescue nil
99: end
100:
101: task :clobber => [paste("clobber_", name)]
102:
103: directory @rdoc_dir
104: task name => [rdoc_target]
105: file rdoc_target => @rdoc_files + [$rakefile] do
106: rm_r @rdoc_dir rescue nil
107: args = option_list + @rdoc_files
108: if @external
109: argstring = args.join(' ')
110: sh %{ruby -Ivendor vender/rd #{argstring}}
111: else
112: require 'rdoc/rdoc'
113: RDoc::RDoc.new.document(args)
114: end
115: end
116: self
117: end
119: def option_list
120: result = @options.dup
121: result << "-o" << @rdoc_dir
122: result << "--main" << quote(main) if main
123: result << "--title" << quote(title) if title
124: result << "-T" << quote(template) if template
125: result
126: end
136: def option_string
137: option_list.join(' ')
138: end
128: def quote(str)
129: if @external
130: "'#{str}'"
131: else
132: str
133: end
134: end