1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
|
require 'rdoc'
require 'rdoc/parsers/parse_rb.rb'
require 'rdoc/parsers/parse_c.rb'
require 'rdoc/parsers/parse_f95.rb'
require 'rdoc/parsers/parse_simple.rb'
require 'rdoc/stats'
require 'rdoc/options'
require 'rdoc/diagram'
require 'find'
require 'fileutils'
require 'time'
module 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.
class RDoc
Generator = Struct.new(:file_name, :class_name, :key)
##
# This is the list of output generator that we support
GENERATORS = {}
$LOAD_PATH.collect do |d|
File.expand_path d
end.find_all do |d|
File.directory? "#{d}/rdoc/generator"
end.each do |dir|
Dir.entries("#{dir}/rdoc/generator").each do |gen|
next unless /(\w+)\.rb$/ =~ gen
type = $1
unless GENERATORS.has_key? type
GENERATORS[type] = Generator.new("rdoc/generator/#{gen}",
"#{type.upcase}".intern,
type)
end
end
end
def initialize
@stats = Stats.new
end
##
# Report an error message and exit
def error(msg)
raise ::RDoc::Error, msg
end
##
# Create an output dir if it doesn't exist. If it does exist, but doesn't
# contain the flag file <tt>created.rid</tt> then we refuse to use it, as
# we may clobber some manually generated documentation
def setup_output_dir(op_dir, force)
flag_file = output_flag_file(op_dir)
if File.exist?(op_dir)
unless File.directory?(op_dir)
error "'#{op_dir}' exists, and is not a directory"
end
begin
created = File.read(flag_file)
rescue SystemCallError
error "\nDirectory #{op_dir} already exists, but it looks like it\n" +
"isn't an RDoc directory. Because RDoc doesn't want to risk\n" +
"destroying any of your existing files, you'll need to\n" +
"specify a different output directory name (using the\n" +
"--op <dir> option).\n\n"
else
last = (Time.parse(created) unless force rescue nil)
end
else
FileUtils.mkdir_p(op_dir)
end
last
end
##
# Update the flag file in an output directory.
def update_output_dir(op_dir, time)
File.open(output_flag_file(op_dir), "w") {|f| f.puts time.rfc2822 }
end
##
# Return the path name of the flag file in an output directory.
def output_flag_file(op_dir)
File.join(op_dir, "created.rid")
end
##
# The .document file contains a list of file and directory name patterns,
# representing candidates for documentation. It may also contain comments
# (starting with '#')
def parse_dot_doc_file(in_dir, filename, options)
# read and strip comments
patterns = File.read(filename).gsub(/#.*/, '')
result = []
patterns.split.each do |patt|
candidates = Dir.glob(File.join(in_dir, patt))
result.concat(normalized_file_list(options, candidates))
end
result
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.
def normalized_file_list(options, relative_files, force_doc = false,
exclude_pattern = nil)
file_list = []
relative_files.each do |rel_file_name|
next if exclude_pattern && exclude_pattern =~ rel_file_name
stat = File.stat(rel_file_name)
case type = stat.ftype
when "file"
next if @last_created and stat.mtime < @last_created
file_list << rel_file_name.sub(/^\.\//, '') if force_doc || ParserFactory.can_parse(rel_file_name)
when "directory"
next if rel_file_name == "CVS" || rel_file_name == ".svn"
dot_doc = File.join(rel_file_name, DOT_DOC_FILENAME)
if File.file?(dot_doc)
file_list.concat(parse_dot_doc_file(rel_file_name, dot_doc, options))
else
file_list.concat(list_files_in_directory(rel_file_name, options))
end
else
raise RDoc::Error, "I can't deal with a #{type} #{rel_file_name}"
end
end
file_list
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.
def list_files_in_directory(dir, options)
files = Dir.glob File.join(dir, "*")
normalized_file_list options, files, false, options.exclude
end
##
# Parse each file on the command line, recursively entering directories.
def parse_files(options)
files = options.files
files = ["."] if files.empty?
file_list = normalized_file_list(options, files, true)
return [] if file_list.empty?
file_info = []
width = file_list.map { |name| name.length }.max + 1
file_list.each do |fn|
$stderr.printf("\n%*s: ", width, fn) unless options.quiet
content = File.open(fn, "r:ascii-8bit") {|f| f.read}
if /coding:\s*(\S+)/ =~ content[/\A(?:.*\n){0,2}/]
if enc = Encoding.find($1)
content.force_encoding(enc)
end
end
top_level = TopLevel.new(fn)
parser = ParserFactory.parser_for(top_level, fn, content, options, @stats)
file_info << parser.scan
@stats.num_files += 1
end
file_info
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: RDoc::Error on error
def document(argv)
TopLevel::reset
options = Options.new GENERATORS
options.parse argv
@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 = ::RDoc::Generator.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
end
end
|