| Class | RDoc::RDoc |
| In: |
lib/rdoc/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 lib/rdoc/rdoc.rb, line 233
233: def document(argv)
234:
235: TopLevel::reset
236:
237: @stats = Stats.new
238:
239: options = Options.instance
240: options.parse(argv, GENERATORS)
241:
242: unless options.all_one_file
243: setup_output_dir(options.op_dir)
244: end
245:
246: file_info = parse_files(options)
247:
248: gen = options.generator
249:
250: $stderr.puts "\nGenerating #{gen.key.upcase}..." unless options.quiet
251:
252: require gen.file_name
253:
254: gen_class = Generators.const_get(gen.class_name)
255:
256: unless file_info.empty?
257: gen = gen_class.for(options)
258:
259: pwd = Dir.pwd
260:
261: Dir.chdir(options.op_dir) unless options.all_one_file
262:
263: begin
264: Diagram.new(file_info, options).draw if options.diagram
265: gen.generate(file_info)
266: ensure
267: Dir.chdir(pwd)
268: end
269: end
270:
271: unless options.quiet
272: puts
273: @stats.print
274: end
275: 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 lib/rdoc/rdoc.rb, line 186
186: def list_files_in_directory(dir, options)
187: normalized_file_list(options, Dir.glob(File.join(dir, "*")), false, options.exclude)
188: 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 lib/rdoc/rdoc.rb, line 158
158: def normalized_file_list(options, relative_files, force_doc = false, exclude_pattern=nil)
159: file_list = []
160:
161: relative_files.each do |rel_file_name|
162: next if exclude_pattern && exclude_pattern =~ rel_file_name
163: case type = File.stat(rel_file_name).ftype
164: when "file"
165: file_list << rel_file_name.sub(/^\.\//, '') if force_doc || ParserFactory.can_parse(rel_file_name)
166: when "directory"
167: next if rel_file_name == "CVS" || rel_file_name == ".svn"
168: dot_doc = File.join(rel_file_name, DOT_DOC_FILENAME)
169: if File.file?(dot_doc)
170: file_list.concat(parse_dot_doc_file(rel_file_name, dot_doc, options))
171: else
172: file_list.concat(list_files_in_directory(rel_file_name, options))
173: end
174: else
175: raise RDocError.new("I can't deal with a #{type} #{rel_file_name}")
176: end
177: end
178: file_list
179: 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 lib/rdoc/rdoc.rb, line 132
132: def parse_dot_doc_file(in_dir, filename, options)
133: # read and strip comments
134: patterns = File.read(filename).gsub(/#.*/, '')
135:
136: result = []
137:
138: patterns.split.each do |patt|
139: candidates = Dir.glob(File.join(in_dir, patt))
140: result.concat(normalized_file_list(options, candidates))
141: end
142: result
143: end
Parse each file on the command line, recursively entering directories
# File lib/rdoc/rdoc.rb, line 194
194: def parse_files(options)
195:
196: file_info = []
197:
198: files = options.files
199: files = ["."] if files.empty?
200:
201: file_list = normalized_file_list(options, files, true)
202:
203: file_list.each do |fn|
204: $stderr.printf("\n%35s: ", File.basename(fn)) unless options.quiet
205:
206: content = File.open(fn, "r") {|f| f.read}
207:
208: top_level = TopLevel.new(fn)
209: parser = ParserFactory.parser_for(top_level, fn, content, options, @stats)
210: file_info << parser.scan
211: @stats.num_files += 1
212: end
213:
214: file_info
215: 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 lib/rdoc/rdoc.rb, line 109
109: def setup_output_dir(op_dir)
110: flag_file = File.join(op_dir, "created.rid")
111: if File.exist?(op_dir)
112: unless File.directory?(op_dir)
113: error "'#{op_dir}' exists, and is not a directory"
114: end
115: unless File.file?(flag_file)
116: error "\nDirectory #{op_dir} already exists, but it looks like it\n" +
117: "isn't an RDoc directory. Because RDoc doesn't want to risk\n" +
118: "destroying any of your existing files, you'll need to\n" +
119: "specify a different output directory name (using the\n" +
120: "--op <dir> option).\n\n"
121: end
122: else
123: File.makedirs(op_dir)
124: end
125: File.open(flag_file, "w") {|f| f.puts Time.now }
126: end