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.
This is the list of output generators that we support
Given an array of flow items and an array of section names, extract those
sections from the flow which have headings corresponding to a section name
in the list. Return them in the order of names in the sections
array.
# File rdoc/usage.rb, line 165 def RDoc.extract_sections(flow, sections) result = [] sections.each do |name| name = name.downcase copy_upto_level = nil flow.each do |item| case item when SM::Flow::H if copy_upto_level && item.level >= copy_upto_level copy_upto_level = nil else if item.text.downcase == name result << item copy_upto_level = item.level end end else if copy_upto_level result << item end end end end if result.empty? puts "Note to developer: requested section(s) [#{sections.join(', ')}] " + "not found" result = flow end result end
# File rdoc/usage.rb, line 141 def RDoc.find_comment(file) catch(:exit) do # skip leading blank lines 0 while (line = gets(file)) && (line =~ /^\s*$/) comment = [] while line && line =~ /^\s*#/ comment << line line = gets(file) end 0 while line && (line = gets(file)) return no_comment if comment.empty? return comment.join end end
Find the first comment in the file (that isn't a shebang line) If the file doesn't start with a comment, report the fact and return empty string
# File rdoc/usage.rb, line 133 def RDoc.gets(file) if (line = file.gets) && (line =~ /^#!/) # shebang throw :exit, find_comment(file) else line end end
Report the fact that no doc comment count be found
# File rdoc/usage.rb, line 199 def RDoc.no_comment $stderr.puts "No usage information available for this program" "" end
Display usage information from the comment at the top of the file. String arguments identify specific sections of the comment to display. An optional integer first argument specifies the exit status (defaults to 0)
# File rdoc/usage.rb, line 81 def RDoc.usage(*args) exit_code = 0 if args.size > 0 status = args[0] if status.respond_to?(:to_int) exit_code = status.to_int args.shift end end # display the usage and exit with the given code usage_no_exit(*args) exit(exit_code) end
Display usage
# File rdoc/usage.rb, line 98 def RDoc.usage_no_exit(*args) main_program_file = caller[-1].sub(/:\d+$/, '') comment = File.open(main_program_file) do |file| find_comment(file) end comment = comment.gsub(/^\s*#/, '') markup = SM::SimpleMarkup.new flow_convertor = SM::ToFlow.new flow = markup.convert(comment, flow_convertor) format = "plain" unless args.empty? flow = extract_sections(flow, args) end options = RI::Options.instance if args = ENV["RI"] options.parse(args.split) end formatter = options.formatter.new(options, "") formatter.display_flow(flow) end
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: RDocError on error
# File rdoc/rdoc.rb, line 249 def document(argv) TopLevel::reset @stats = Stats.new options = Options.instance options.parse(argv, GENERATORS) @last_created = nil unless options.all_one_file @last_created = setup_output_dir(options.op_dir, options.force_update) end start_time = Time.now file_info = parse_files(options) if file_info.empty? $stderr.puts "\nNo newer files." unless options.quiet else gen = options.generator $stderr.puts "\nGenerating #{gen.key.upcase}..." unless options.quiet require gen.file_name gen_class = Generators.const_get(gen.class_name) gen = gen_class.for(options) pwd = Dir.pwd Dir.chdir(options.op_dir) unless options.all_one_file begin Diagram.new(file_info, options).draw if options.diagram gen.generate(file_info) update_output_dir(".", start_time) ensure Dir.chdir(pwd) end end unless options.quiet puts @stats.print end end