| Class | RDoc::RDoc |
| In: |
rdoc.rb
|
| Parent: | Object |
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.
| Generator | = | Struct.new(:file_name, :class_name, :key) | This is the list of output generators that we support | |
| GENERATORS | = | {} |
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.
# File rdoc.rb, line 253
253: def document(argv)
254:
255: TopLevel::reset
256:
257: @stats = Stats.new
258:
259: options = Options.instance
260: options.parse(argv, GENERATORS)
261:
262: @last_created = nil
263: unless options.all_one_file
264: @last_created = setup_output_dir(options.op_dir, options.force_update)
265: end
266: start_time = Time.now
267:
268: file_info = parse_files(options)
269:
270: if file_info.empty?
271: $stderr.puts "\nNo newer files." unless options.quiet
272: else
273: gen = options.generator
274:
275: $stderr.puts "\nGenerating #{gen.key.upcase}..." unless options.quiet
276:
277: require gen.file_name
278:
279: gen_class = Generators.const_get(gen.class_name)
280: gen = gen_class.for(options)
281:
282: pwd = Dir.pwd
283:
284: Dir.chdir(options.op_dir) unless options.all_one_file
285:
286: begin
287: Diagram.new(file_info, options).draw if options.diagram
288: gen.generate(file_info)
289: update_output_dir(".", start_time)
290: ensure
291: Dir.chdir(pwd)
292: end
293: end
294:
295: unless options.quiet
296: puts
297: @stats.print
298: end
299: end
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 rdoc.rb, line 206
206: def list_files_in_directory(dir, options)
207: normalized_file_list(options, Dir.glob(File.join(dir, "*")), false, options.exclude)
208: end
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 explicity.
# File rdoc.rb, line 176
176: def normalized_file_list(options, relative_files, force_doc = false, exclude_pattern=nil)
177: file_list = []
178:
179: relative_files.each do |rel_file_name|
180: next if exclude_pattern && exclude_pattern =~ rel_file_name
181: stat = File.stat(rel_file_name)
182: case type = stat.ftype
183: when "file"
184: next if @last_created and stat.mtime < @last_created
185: file_list << rel_file_name.sub(/^\.\//, '') if force_doc || ParserFactory.can_parse(rel_file_name)
186: when "directory"
187: next if rel_file_name == "CVS" || rel_file_name == ".svn"
188: dot_doc = File.join(rel_file_name, DOT_DOC_FILENAME)
189: if File.file?(dot_doc)
190: file_list.concat(parse_dot_doc_file(rel_file_name, dot_doc, options))
191: else
192: file_list.concat(list_files_in_directory(rel_file_name, options))
193: end
194: else
195: raise RDocError.new("I can't deal with a #{type} #{rel_file_name}")
196: end
197: end
198: file_list
199: end
Return the path name of the flag file in an output directory.
# File rdoc.rb, line 143
143: def output_flag_file(op_dir)
144: File.join(op_dir, "created.rid")
145: end
The .document file contains a list of file and directory name patterns, representing candidates for documentation. It may also contain comments (starting with ’#’)
# File rdoc.rb, line 150
150: def parse_dot_doc_file(in_dir, filename, options)
151: # read and strip comments
152: patterns = File.read(filename).gsub(/#.*/, '')
153:
154: result = []
155:
156: patterns.split.each do |patt|
157: candidates = Dir.glob(File.join(in_dir, patt))
158: result.concat(normalized_file_list(options, candidates))
159: end
160: result
161: end
Parse each file on the command line, recursively entering directories
# File rdoc.rb, line 214
214: def parse_files(options)
215:
216: file_info = []
217:
218: files = options.files
219: files = ["."] if files.empty?
220:
221: file_list = normalized_file_list(options, files, true)
222:
223: file_list.each do |fn|
224: $stderr.printf("\n%35s: ", File.basename(fn)) unless options.quiet
225:
226: content = File.open(fn, "r") {|f| f.read}
227:
228: top_level = TopLevel.new(fn)
229: parser = ParserFactory.parser_for(top_level, fn, content, options, @stats)
230: file_info << parser.scan
231: @stats.num_files += 1
232: end
233:
234: file_info
235: end
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 rdoc.rb, line 114
114: def setup_output_dir(op_dir, force)
115: flag_file = output_flag_file(op_dir)
116: if File.exist?(op_dir)
117: unless File.directory?(op_dir)
118: error "'#{op_dir}' exists, and is not a directory"
119: end
120: begin
121: created = File.read(flag_file)
122: rescue SystemCallError
123: error "\nDirectory #{op_dir} already exists, but it looks like it\n" +
124: "isn't an RDoc directory. Because RDoc doesn't want to risk\n" +
125: "destroying any of your existing files, you'll need to\n" +
126: "specify a different output directory name (using the\n" +
127: "--op <dir> option).\n\n"
128: else
129: last = (Time.parse(created) unless force rescue nil)
130: end
131: else
132: File.makedirs(op_dir)
133: end
134: last
135: end