RDoc::RDoc

Encapsulate the production of rdoc documentation. Basically you can use this as you would invoke rdoc from the command line:

  rdoc = RDoc::RDoc.new
  rdoc.document(args)

Where args is an array of strings, each corresponding to an argument you’d give rdoc on the command line. See rdoc/rdoc.rb for details.

Constants

GENERATORS: This is the list of supported output generators

Attributes

exclude[RW]

File pattern to exclude

generator[RW]

Generator instance used for creating output

last_modified[R]

Hash of files and their last modified times.

options[RW]

RDoc options

stats[R]

Accessor for statistics. Available after each call to parse_files

Public Class Methods

add_generator(klass) click to toggle source

Add klass that can generate output after parsing

    # File lib/rdoc/rdoc.rb, line 63
63:   def self.add_generator(klass)
64:     name = klass.name.sub(/^RDoc::Generator::/, '').downcase
65:     GENERATORS[name] = klass
66:   end

current() click to toggle source

Active RDoc::RDoc instance

    # File lib/rdoc/rdoc.rb, line 71
71:   def self.current
72:     @current
73:   end

current=(rdoc) click to toggle source

Sets the active RDoc::RDoc instance

    # File lib/rdoc/rdoc.rb, line 78
78:   def self.current=(rdoc)
79:     @current = rdoc
80:   end

new() click to toggle source

    # File lib/rdoc/rdoc.rb, line 82
82:   def initialize
83:     @current       = nil
84:     @exclude       = nil
85:     @generator     = nil
86:     @last_modified = {}
87:     @old_siginfo   = nil
88:     @options       = nil
89:     @stats         = nil
90:   end

Public Instance Methods

document(argv) click to toggle source

Format up one or more files according to the given arguments.

For simplicity, argv is an array of strings, equivalent to the strings that would be passed on the command line. (This isn’t a coincidence, as we do pass in ARGV when running interactively). For a list of options, see rdoc/rdoc.rb. By default, output will be stored in a directory called doc below the current directory, so make sure you’re somewhere writable before invoking.

Throws: RDoc::Error on error

     # File lib/rdoc/rdoc.rb, line 353
353:   def document(argv)
354:     RDoc::TopLevel.reset
355:     RDoc::Parser::C.reset
356: 
357:     @options = RDoc::Options.new
358:     @options.parse argv
359: 
360:     if @options.pipe then
361:       handle_pipe
362:       exit
363:     end
364: 
365:     @exclude = @options.exclude
366: 
367:     @last_modified = setup_output_dir @options.op_dir, @options.force_update
368: 
369:     start_time = Time.now
370: 
371:     file_info = parse_files @options.files
372: 
373:     @options.title = "RDoc Documentation"
374: 
375:     if file_info.empty?
376:       $stderr.puts "\nNo newer files." unless @options.quiet
377:     else
378:       gen_klass = @options.generator
379: 
380:       unless @options.quiet then
381:         $stderr.puts "\nGenerating #{gen_klass.name.sub(/^.*::/, '')}..."
382:       end
383: 
384:       @generator = gen_klass.for @options
385: 
386:       pwd = Dir.pwd
387: 
388:       Dir.chdir @options.op_dir do
389:         begin
390:           self.class.current = self
391: 
392:           @generator.generate file_info
393:           update_output_dir ".", start_time, @last_modified
394:         ensure
395:           self.class.current = nil
396:         end
397:       end
398:     end
399: 
400:     unless @options.quiet or not @stats then
401:       puts
402:       @stats.print
403:     end
404:   end

error(msg) click to toggle source

Report an error message and exit

    # File lib/rdoc/rdoc.rb, line 95
95:   def error(msg)
96:     raise RDoc::Error, msg
97:   end

gather_files(files) click to toggle source

Gathers a set of parseable files from the files and directories listed in files.

     # File lib/rdoc/rdoc.rb, line 103
103:   def gather_files files
104:     files = ["."] if files.empty?
105: 
106:     file_list = normalized_file_list files, true, @exclude
107: 
108:     file_list = file_list.uniq
109: 
110:     file_list = remove_unparseable file_list
111:   end

handle_pipe() click to toggle source

Turns RDoc from stdin into HTML

     # File lib/rdoc/rdoc.rb, line 116
116:   def handle_pipe
117:     @html = RDoc::Markup::ToHtml.new
118: 
119:     out = @html.convert $stdin.read
120: 
121:     $stdout.write out
122:   end

install_siginfo_handler() click to toggle source

Installs a siginfo handler that prints the current filename.

     # File lib/rdoc/rdoc.rb, line 127
127:   def install_siginfo_handler
128:     return unless Signal.list.include? 'INFO'
129: 
130:     @old_siginfo = trap 'INFO' do
131:       puts @current if @current
132:     end
133:   end

list_files_in_directory(dir) click to toggle source

Return a list of the files to be processed in a directory. We know that this directory doesn’t have a .document file, so we’re looking for real files. However we may well contain subdirectories which must be tested for .document files.

     # File lib/rdoc/rdoc.rb, line 269
269:   def list_files_in_directory dir
270:     files = Dir.glob File.join(dir, "*")
271: 
272:     normalized_file_list files, false, @options.exclude
273:   end

normalized_file_list(relative_files, force_doc = false, exclude_pattern = nil) click to toggle source

Given a list of files and directories, create a list of all the Ruby files they contain.

If force_doc is true we always add the given files, if false, only add files that we guarantee we can parse. It is true when looking at files given on the command line, false when recursing through subdirectories.

The effect of this is that if you want a file with a non-standard extension parsed, you must name it explicitly.

     # File lib/rdoc/rdoc.rb, line 228
228:   def normalized_file_list(relative_files, force_doc = false,
229:                            exclude_pattern = nil)
230:     file_list = []
231: 
232:     relative_files.each do |rel_file_name|
233:       next if exclude_pattern && exclude_pattern =~ rel_file_name
234:       stat = File.stat rel_file_name rescue next
235: 
236:       case type = stat.ftype
237:       when "file" then
238:         next if last_modified = @last_modified[rel_file_name] and
239:                 stat.mtime.to_i <= last_modified.to_i
240: 
241:         if force_doc or RDoc::Parser.can_parse(rel_file_name) then
242:           file_list << rel_file_name.sub(/^\.\//, '')
243:           @last_modified[rel_file_name] = stat.mtime
244:         end
245:       when "directory" then
246:         next if rel_file_name == "CVS" || rel_file_name == ".svn"
247: 
248:         dot_doc = File.join rel_file_name, RDoc::DOT_DOC_FILENAME
249: 
250:         if File.file? dot_doc then
251:           file_list << parse_dot_doc_file(rel_file_name, dot_doc)
252:         else
253:           file_list << list_files_in_directory(rel_file_name)
254:         end
255:       else
256:         raise RDoc::Error, "I can't deal with a #{type} #{rel_file_name}"
257:       end
258:     end
259: 
260:     file_list.flatten
261:   end

output_flag_file(op_dir) click to toggle source

Return the path name of the flag file in an output directory.

     # File lib/rdoc/rdoc.rb, line 193
193:   def output_flag_file(op_dir)
194:     File.join op_dir, "created.rid"
195:   end

parse_dot_doc_file(in_dir, filename) click to toggle source

The .document file contains a list of file and directory name patterns, representing candidates for documentation. It may also contain comments (starting with ’#’)

     # File lib/rdoc/rdoc.rb, line 202
202:   def parse_dot_doc_file in_dir, filename
203:     # read and strip comments
204:     patterns = File.read(filename).gsub(/#.*/, '')
205: 
206:     result = []
207: 
208:     patterns.split.each do |patt|
209:       candidates = Dir.glob(File.join(in_dir, patt))
210:       result.concat normalized_file_list(candidates)
211:     end
212: 
213:     result
214:   end

parse_file(filename) click to toggle source

Parses filename and returns an RDoc::TopLevel

     # File lib/rdoc/rdoc.rb, line 278
278:   def parse_file filename
279:     @stats.add_file filename
280:     content = read_file_contents filename
281: 
282:     return unless content
283: 
284:     top_level = RDoc::TopLevel.new filename
285: 
286:     parser = RDoc::Parser.for top_level, filename, content, @options, @stats
287: 
288:     return unless parser
289: 
290:     parser.scan
291:   rescue => e
292:     $stderr.puts Before reporting this, could you check that the file you're documentingcompiles cleanly--RDoc is not a full Ruby parser, and gets confused easily iffed invalid programs.The internal error was:\t(#{e.class}) #{e.message}
293: 
294:     $stderr.puts e.backtrace.join("\n\t") if $RDOC_DEBUG
295: 
296:     raise e
297:     nil
298:   end

parse_files(files) click to toggle source

Parse each file on the command line, recursively entering directories.

     # File lib/rdoc/rdoc.rb, line 312
312:   def parse_files files
313:     file_list = gather_files files
314: 
315:     return [] if file_list.empty?
316: 
317:     file_info = []
318: 
319:     @stats = RDoc::Stats.new file_list.size, @options.verbosity
320:     @stats.begin_adding
321: 
322:     file_info = file_list.map do |filename|
323:       @current = filename
324:       parse_file filename
325:     end.compact
326: 
327:     @stats.done_adding
328: 
329:     file_info
330:   end

read_file_contents(filename) click to toggle source

     # File lib/rdoc/rdoc.rb, line 406
406:   def read_file_contents(filename)
407:     content = open filename, "rb" do |f| f.read end
408:     RDoc::Parser.set_encoding(content)
409:     content
410:   rescue Errno::EISDIR, Errno::ENOENT
411:     nil
412:   end

remove_siginfo_handler() click to toggle source

Removes a siginfo handler and replaces the previous

     # File lib/rdoc/rdoc.rb, line 417
417:   def remove_siginfo_handler
418:     return unless Signal.list.key? 'INFO'
419: 
420:     handler = @old_siginfo || 'DEFAULT'
421: 
422:     trap 'INFO', handler
423:   end

remove_unparseable(files) click to toggle source

Removes file extensions known to be unparseable from files

     # File lib/rdoc/rdoc.rb, line 335
335:   def remove_unparseable files
336:     files.reject do |file|
337:       file =~ /\.(?:class|eps|erb|scpt\.txt|ttf|yml)$/
338:     end
339:   end

setup_output_dir(dir, force) click to toggle source

Create an output dir if it doesn’t exist. If it does exist, but doesn’t contain the flag file created.rid then we refuse to use it, as we may clobber some manually generated documentation

     # File lib/rdoc/rdoc.rb, line 140
140:   def setup_output_dir(dir, force)
141:     flag_file = output_flag_file dir
142: 
143:     last = {}
144: 
145:     if File.exist? dir then
146:       error "#{dir} exists and is not a directory" unless File.directory? dir
147: 
148:       begin
149:         open flag_file do |io|
150:           unless force then
151:             Time.parse io.gets
152: 
153:             io.each do |line|
154:               file, time = line.split "\t", 2
155:               time = Time.parse(time) rescue next
156:               last[file] = time
157:             end
158:           end
159:         end
160:       rescue SystemCallError, TypeError
161:         error Directory #{dir} already exists, but it looks like it isn't an RDoc directory.Because RDoc doesn't want to risk destroying any of your existing files,you'll need to specify a different output directory name (using the --op <dir>option)
162:       end
163:     else
164:       FileUtils.mkdir_p dir
165:     end
166: 
167:     last
168:   end

update_output_dir(op_dir, time, last = {}) click to toggle source

Update the flag file in an output directory.

     # File lib/rdoc/rdoc.rb, line 181
181:   def update_output_dir(op_dir, time, last = {})
182:     open output_flag_file(op_dir), "w" do |f|
183:       f.puts time.rfc2822
184:       last.each do |n, t|
185:         f.puts "#{n}\t#{t.rfc2822}"
186:       end
187:     end
188:   end

Home Classes Methods

In Files

Parent

Methods

Files

Class Index

RDoc::RDoc

Constants

Attributes

Public Class Methods

Public Instance Methods