1 | # We're responsible for generating all the HTML files
|
---|
2 | # from the object tree defined in code_objects.rb. We
|
---|
3 | # generate:
|
---|
4 | #
|
---|
5 | # [files] an html file for each input file given. These
|
---|
6 | # input files appear as objects of class
|
---|
7 | # TopLevel
|
---|
8 | #
|
---|
9 | # [classes] an html file for each class or module encountered.
|
---|
10 | # These classes are not grouped by file: if a file
|
---|
11 | # contains four classes, we'll generate an html
|
---|
12 | # file for the file itself, and four html files
|
---|
13 | # for the individual classes.
|
---|
14 | #
|
---|
15 | # [indices] we generate three indices for files, classes,
|
---|
16 | # and methods. These are displayed in a browser
|
---|
17 | # like window with three index panes across the
|
---|
18 | # top and the selected description below
|
---|
19 | #
|
---|
20 | # Method descriptions appear in whatever entity (file, class,
|
---|
21 | # or module) that contains them.
|
---|
22 | #
|
---|
23 | # We generate files in a structure below a specified subdirectory,
|
---|
24 | # normally +doc+.
|
---|
25 | #
|
---|
26 | # opdir
|
---|
27 | # |
|
---|
28 | # |___ files
|
---|
29 | # | |__ per file summaries
|
---|
30 | # |
|
---|
31 | # |___ classes
|
---|
32 | # |__ per class/module descriptions
|
---|
33 | #
|
---|
34 | # HTML is generated using the Template class.
|
---|
35 | #
|
---|
36 |
|
---|
37 | require 'ftools'
|
---|
38 |
|
---|
39 | require 'rdoc/options'
|
---|
40 | require 'rdoc/template'
|
---|
41 | require 'rdoc/markup/simple_markup'
|
---|
42 | require 'rdoc/markup/simple_markup/to_html'
|
---|
43 | require 'cgi'
|
---|
44 |
|
---|
45 | module Generators
|
---|
46 |
|
---|
47 | # Name of sub-direcories that hold file and class/module descriptions
|
---|
48 |
|
---|
49 | FILE_DIR = "files"
|
---|
50 | CLASS_DIR = "classes"
|
---|
51 | CSS_NAME = "rdoc-style.css"
|
---|
52 |
|
---|
53 |
|
---|
54 | ##
|
---|
55 | # Build a hash of all items that can be cross-referenced.
|
---|
56 | # This is used when we output required and included names:
|
---|
57 | # if the names appear in this hash, we can generate
|
---|
58 | # an html cross reference to the appropriate description.
|
---|
59 | # We also use this when parsing comment blocks: any decorated
|
---|
60 | # words matching an entry in this list are hyperlinked.
|
---|
61 |
|
---|
62 | class AllReferences
|
---|
63 | @@refs = {}
|
---|
64 |
|
---|
65 | def AllReferences::reset
|
---|
66 | @@refs = {}
|
---|
67 | end
|
---|
68 |
|
---|
69 | def AllReferences.add(name, html_class)
|
---|
70 | @@refs[name] = html_class
|
---|
71 | end
|
---|
72 |
|
---|
73 | def AllReferences.[](name)
|
---|
74 | @@refs[name]
|
---|
75 | end
|
---|
76 |
|
---|
77 | def AllReferences.keys
|
---|
78 | @@refs.keys
|
---|
79 | end
|
---|
80 | end
|
---|
81 |
|
---|
82 |
|
---|
83 | ##
|
---|
84 | # Subclass of the SM::ToHtml class that supports looking
|
---|
85 | # up words in the AllReferences list. Those that are
|
---|
86 | # found (like AllReferences in this comment) will
|
---|
87 | # be hyperlinked
|
---|
88 |
|
---|
89 | class HyperlinkHtml < SM::ToHtml
|
---|
90 | # We need to record the html path of our caller so we can generate
|
---|
91 | # correct relative paths for any hyperlinks that we find
|
---|
92 | def initialize(from_path, context)
|
---|
93 | super()
|
---|
94 | @from_path = from_path
|
---|
95 |
|
---|
96 | @parent_name = context.parent_name
|
---|
97 | @parent_name += "::" if @parent_name
|
---|
98 | @context = context
|
---|
99 | end
|
---|
100 |
|
---|
101 | # We're invoked when any text matches the CROSSREF pattern
|
---|
102 | # (defined in MarkUp). If we fine the corresponding reference,
|
---|
103 | # generate a hyperlink. If the name we're looking for contains
|
---|
104 | # no punctuation, we look for it up the module/class chain. For
|
---|
105 | # example, HyperlinkHtml is found, even without the Generators::
|
---|
106 | # prefix, because we look for it in module Generators first.
|
---|
107 |
|
---|
108 | def handle_special_CROSSREF(special)
|
---|
109 | name = special.text
|
---|
110 | if name[0,1] == '#'
|
---|
111 | lookup = name[1..-1]
|
---|
112 | name = lookup unless Options.instance.show_hash
|
---|
113 | else
|
---|
114 | lookup = name
|
---|
115 | end
|
---|
116 |
|
---|
117 | # Find class, module, or method in class or module.
|
---|
118 | if /([A-Z]\w*)[.\#](\w+[!?=]?)/ =~ lookup
|
---|
119 | container = $1
|
---|
120 | method = $2
|
---|
121 | ref = @context.find_symbol(container, method)
|
---|
122 | elsif /([A-Za-z]\w*)[.\#](\w+(\([\.\w+\*\/\+\-\=\<\>]+\))?)/ =~ lookup
|
---|
123 | container = $1
|
---|
124 | method = $2
|
---|
125 | ref = @context.find_symbol(container, method)
|
---|
126 | else
|
---|
127 | ref = @context.find_symbol(lookup)
|
---|
128 | end
|
---|
129 |
|
---|
130 | if ref and ref.document_self
|
---|
131 | "<a href=\"#{ref.as_href(@from_path)}\">#{name}</a>"
|
---|
132 | else
|
---|
133 | name
|
---|
134 | end
|
---|
135 | end
|
---|
136 |
|
---|
137 |
|
---|
138 | # Generate a hyperlink for url, labeled with text. Handle the
|
---|
139 | # special cases for img: and link: described under handle_special_HYPEDLINK
|
---|
140 | def gen_url(url, text)
|
---|
141 | if url =~ /([A-Za-z]+):(.*)/
|
---|
142 | type = $1
|
---|
143 | path = $2
|
---|
144 | else
|
---|
145 | type = "http"
|
---|
146 | path = url
|
---|
147 | url = "http://#{url}"
|
---|
148 | end
|
---|
149 |
|
---|
150 | if type == "link"
|
---|
151 | if path[0,1] == '#' # is this meaningful?
|
---|
152 | url = path
|
---|
153 | else
|
---|
154 | url = HTMLGenerator.gen_url(@from_path, path)
|
---|
155 | end
|
---|
156 | end
|
---|
157 |
|
---|
158 | if (type == "http" || type == "link") &&
|
---|
159 | url =~ /\.(gif|png|jpg|jpeg|bmp)$/
|
---|
160 |
|
---|
161 | "<img src=\"#{url}\" />"
|
---|
162 | else
|
---|
163 | "<a href=\"#{url}\">#{text.sub(%r{^#{type}:/*}, '')}</a>"
|
---|
164 | end
|
---|
165 | end
|
---|
166 |
|
---|
167 | # And we're invoked with a potential external hyperlink mailto:
|
---|
168 | # just gets inserted. http: links are checked to see if they
|
---|
169 | # reference an image. If so, that image gets inserted using an
|
---|
170 | # <img> tag. Otherwise a conventional <a href> is used. We also
|
---|
171 | # support a special type of hyperlink, link:, which is a reference
|
---|
172 | # to a local file whose path is relative to the --op directory.
|
---|
173 |
|
---|
174 | def handle_special_HYPERLINK(special)
|
---|
175 | url = special.text
|
---|
176 | gen_url(url, url)
|
---|
177 | end
|
---|
178 |
|
---|
179 | # HEre's a hypedlink where the label is different to the URL
|
---|
180 | # <label>[url]
|
---|
181 | #
|
---|
182 |
|
---|
183 | def handle_special_TIDYLINK(special)
|
---|
184 | text = special.text
|
---|
185 | # unless text =~ /(\S+)\[(.*?)\]/
|
---|
186 | unless text =~ /\{(.*?)\}\[(.*?)\]/ or text =~ /(\S+)\[(.*?)\]/
|
---|
187 | return text
|
---|
188 | end
|
---|
189 | label = $1
|
---|
190 | url = $2
|
---|
191 | gen_url(url, label)
|
---|
192 | end
|
---|
193 |
|
---|
194 | end
|
---|
195 |
|
---|
196 |
|
---|
197 |
|
---|
198 | #####################################################################
|
---|
199 | #
|
---|
200 | # Handle common markup tasks for the various Html classes
|
---|
201 | #
|
---|
202 |
|
---|
203 | module MarkUp
|
---|
204 |
|
---|
205 | # Convert a string in markup format into HTML. We keep a cached
|
---|
206 | # SimpleMarkup object lying around after the first time we're
|
---|
207 | # called per object.
|
---|
208 |
|
---|
209 | def markup(str, remove_para=false)
|
---|
210 | return '' unless str
|
---|
211 | unless defined? @markup
|
---|
212 | @markup = SM::SimpleMarkup.new
|
---|
213 |
|
---|
214 | # class names, variable names, or instance variables
|
---|
215 | @markup.add_special(/(
|
---|
216 | \w+(::\w+)*[.\#]\w+(\([\.\w+\*\/\+\-\=\<\>]+\))? # A::B.meth(**) (for operator in Fortran95)
|
---|
217 | | \#\w+(\([.\w\*\/\+\-\=\<\>]+\))? # meth(**) (for operator in Fortran95)
|
---|
218 | | \b([A-Z]\w*(::\w+)*[.\#]\w+) # A::B.meth
|
---|
219 | | \b([A-Z]\w+(::\w+)*) # A::B..
|
---|
220 | | \#\w+[!?=]? # #meth_name
|
---|
221 | | \b\w+([_\/\.]+\w+)*[!?=]? # meth_name
|
---|
222 | )/x,
|
---|
223 | :CROSSREF)
|
---|
224 |
|
---|
225 | # external hyperlinks
|
---|
226 | @markup.add_special(/((link:|https?:|mailto:|ftp:|www\.)\S+\w)/, :HYPERLINK)
|
---|
227 |
|
---|
228 | # and links of the form <text>[<url>]
|
---|
229 | @markup.add_special(/(((\{.*?\})|\b\S+?)\[\S+?\.\S+?\])/, :TIDYLINK)
|
---|
230 | # @markup.add_special(/\b(\S+?\[\S+?\.\S+?\])/, :TIDYLINK)
|
---|
231 |
|
---|
232 | end
|
---|
233 | unless defined? @html_formatter
|
---|
234 | @html_formatter = HyperlinkHtml.new(self.path, self)
|
---|
235 | end
|
---|
236 |
|
---|
237 | # Convert leading comment markers to spaces, but only
|
---|
238 | # if all non-blank lines have them
|
---|
239 |
|
---|
240 | if str =~ /^(?>\s*)[^\#]/
|
---|
241 | content = str
|
---|
242 | else
|
---|
243 | content = str.gsub(/^\s*(#+)/) { $1.tr('#',' ') }
|
---|
244 | end
|
---|
245 |
|
---|
246 | res = @markup.convert(content, @html_formatter)
|
---|
247 | if remove_para
|
---|
248 | res.sub!(/^<p>/, '')
|
---|
249 | res.sub!(/<\/p>$/, '')
|
---|
250 | end
|
---|
251 | res
|
---|
252 | end
|
---|
253 |
|
---|
254 | # Qualify a stylesheet URL; if if +css_name+ does not begin with '/' or
|
---|
255 | # 'http[s]://', prepend a prefix relative to +path+. Otherwise, return it
|
---|
256 | # unmodified.
|
---|
257 |
|
---|
258 | def style_url(path, css_name=nil)
|
---|
259 | # $stderr.puts "style_url( #{path.inspect}, #{css_name.inspect} )"
|
---|
260 | css_name ||= CSS_NAME
|
---|
261 | if %r{^(https?:/)?/} =~ css_name
|
---|
262 | return css_name
|
---|
263 | else
|
---|
264 | return HTMLGenerator.gen_url(path, css_name)
|
---|
265 | end
|
---|
266 | end
|
---|
267 |
|
---|
268 | # Build a webcvs URL with the given 'url' argument. URLs with a '%s' in them
|
---|
269 | # get the file's path sprintfed into them; otherwise they're just catenated
|
---|
270 | # together.
|
---|
271 |
|
---|
272 | def cvs_url(url, full_path)
|
---|
273 | if /%s/ =~ url
|
---|
274 | return sprintf( url, full_path )
|
---|
275 | else
|
---|
276 | return url + full_path
|
---|
277 | end
|
---|
278 | end
|
---|
279 | end
|
---|
280 |
|
---|
281 |
|
---|
282 | #####################################################################
|
---|
283 | #
|
---|
284 | # A Context is built by the parser to represent a container: contexts
|
---|
285 | # hold classes, modules, methods, require lists and include lists.
|
---|
286 | # ClassModule and TopLevel are the context objects we process here
|
---|
287 | #
|
---|
288 | class ContextUser
|
---|
289 |
|
---|
290 | include MarkUp
|
---|
291 |
|
---|
292 | attr_reader :context
|
---|
293 |
|
---|
294 | def initialize(context, options)
|
---|
295 | @context = context
|
---|
296 | @options = options
|
---|
297 | end
|
---|
298 |
|
---|
299 | # convenience method to build a hyperlink
|
---|
300 | def href(link, cls, name)
|
---|
301 | %{<a href="#{link}" class="#{cls}">#{name}</a>} #"
|
---|
302 | end
|
---|
303 |
|
---|
304 | # return a reference to outselves to be used as an href=
|
---|
305 | # the form depends on whether we're all in one file
|
---|
306 | # or in multiple files
|
---|
307 |
|
---|
308 | def as_href(from_path)
|
---|
309 | if @options.all_one_file
|
---|
310 | "#" + path
|
---|
311 | else
|
---|
312 | HTMLGenerator.gen_url(from_path, path)
|
---|
313 | end
|
---|
314 | end
|
---|
315 |
|
---|
316 | # Create a list of HtmlMethod objects for each method
|
---|
317 | # in the corresponding context object. If the @options.show_all
|
---|
318 | # variable is set (corresponding to the <tt>--all</tt> option,
|
---|
319 | # we include all methods, otherwise just the public ones.
|
---|
320 |
|
---|
321 | def collect_methods
|
---|
322 | list = @context.method_list
|
---|
323 | unless @options.show_all
|
---|
324 | list = list.find_all {|m| m.visibility == :public || m.visibility == :protected || m.force_documentation }
|
---|
325 | end
|
---|
326 | @methods = list.collect {|m| HtmlMethod.new(m, self, @options) }
|
---|
327 | end
|
---|
328 |
|
---|
329 | # Build a summary list of all the methods in this context
|
---|
330 | def build_method_summary_list(path_prefix="")
|
---|
331 | collect_methods unless @methods
|
---|
332 | meths = @methods.sort
|
---|
333 | res = []
|
---|
334 | meths.each do |meth|
|
---|
335 | res << {
|
---|
336 | "name" => CGI.escapeHTML(meth.name),
|
---|
337 | "aref" => "#{path_prefix}\##{meth.aref}"
|
---|
338 | }
|
---|
339 | end
|
---|
340 | res
|
---|
341 | end
|
---|
342 |
|
---|
343 |
|
---|
344 | # Build a list of aliases for which we couldn't find a
|
---|
345 | # corresponding method
|
---|
346 | def build_alias_summary_list(section)
|
---|
347 | values = []
|
---|
348 | @context.aliases.each do |al|
|
---|
349 | next unless al.section == section
|
---|
350 | res = {
|
---|
351 | 'old_name' => al.old_name,
|
---|
352 | 'new_name' => al.new_name,
|
---|
353 | }
|
---|
354 | if al.comment && !al.comment.empty?
|
---|
355 | res['desc'] = markup(al.comment, true)
|
---|
356 | end
|
---|
357 | values << res
|
---|
358 | end
|
---|
359 | values
|
---|
360 | end
|
---|
361 |
|
---|
362 | # Build a list of constants
|
---|
363 | def build_constants_summary_list(section)
|
---|
364 | values = []
|
---|
365 | @context.constants.each do |co|
|
---|
366 | next unless co.section == section
|
---|
367 | res = {
|
---|
368 | 'name' => co.name,
|
---|
369 | 'value' => CGI.escapeHTML(co.value)
|
---|
370 | }
|
---|
371 | res['desc'] = markup(co.comment, true) if co.comment && !co.comment.empty?
|
---|
372 | values << res
|
---|
373 | end
|
---|
374 | values
|
---|
375 | end
|
---|
376 |
|
---|
377 | def build_requires_list(context)
|
---|
378 | potentially_referenced_list(context.requires) {|fn| [fn + ".rb"] }
|
---|
379 | end
|
---|
380 |
|
---|
381 | def build_include_list(context)
|
---|
382 | potentially_referenced_list(context.includes)
|
---|
383 | end
|
---|
384 |
|
---|
385 | # Build a list from an array of <i>Htmlxxx</i> items. Look up each
|
---|
386 | # in the AllReferences hash: if we find a corresponding entry,
|
---|
387 | # we generate a hyperlink to it, otherwise just output the name.
|
---|
388 | # However, some names potentially need massaging. For example,
|
---|
389 | # you may require a Ruby file without the .rb extension,
|
---|
390 | # but the file names we know about may have it. To deal with
|
---|
391 | # this, we pass in a block which performs the massaging,
|
---|
392 | # returning an array of alternative names to match
|
---|
393 |
|
---|
394 | def potentially_referenced_list(array)
|
---|
395 | res = []
|
---|
396 | array.each do |i|
|
---|
397 | ref = AllReferences[i.name]
|
---|
398 | # if !ref
|
---|
399 | # container = @context.parent
|
---|
400 | # while !ref && container
|
---|
401 | # name = container.name + "::" + i.name
|
---|
402 | # ref = AllReferences[name]
|
---|
403 | # container = container.parent
|
---|
404 | # end
|
---|
405 | # end
|
---|
406 |
|
---|
407 | ref = @context.find_symbol(i.name)
|
---|
408 | ref = ref.viewer if ref
|
---|
409 |
|
---|
410 | if !ref && block_given?
|
---|
411 | possibles = yield(i.name)
|
---|
412 | while !ref and !possibles.empty?
|
---|
413 | ref = AllReferences[possibles.shift]
|
---|
414 | end
|
---|
415 | end
|
---|
416 | h_name = CGI.escapeHTML(i.name)
|
---|
417 | if ref and ref.document_self
|
---|
418 | path = url(ref.path)
|
---|
419 | res << { "name" => h_name, "aref" => path }
|
---|
420 | else
|
---|
421 | res << { "name" => h_name }
|
---|
422 | end
|
---|
423 | end
|
---|
424 | res
|
---|
425 | end
|
---|
426 |
|
---|
427 | # Build an array of arrays of method details. The outer array has up
|
---|
428 | # to six entries, public, private, and protected for both class
|
---|
429 | # methods, the other for instance methods. The inner arrays contain
|
---|
430 | # a hash for each method
|
---|
431 |
|
---|
432 | def build_method_detail_list(section)
|
---|
433 | outer = []
|
---|
434 |
|
---|
435 | methods = @methods.sort
|
---|
436 | for singleton in [true, false]
|
---|
437 | for vis in [ :public, :protected, :private ]
|
---|
438 | res = []
|
---|
439 | methods.each do |m|
|
---|
440 | if m.section == section and
|
---|
441 | m.document_self and
|
---|
442 | m.visibility == vis and
|
---|
443 | m.singleton == singleton
|
---|
444 | row = {}
|
---|
445 | if m.call_seq
|
---|
446 | row["callseq"] = m.call_seq.gsub(/->/, '→')
|
---|
447 | else
|
---|
448 | row["name"] = CGI.escapeHTML(m.name)
|
---|
449 | row["params"] = m.params
|
---|
450 | end
|
---|
451 | desc = m.description.strip
|
---|
452 | row["m_desc"] = desc unless desc.empty?
|
---|
453 | row["aref"] = m.aref
|
---|
454 | row["visibility"] = m.visibility.to_s
|
---|
455 |
|
---|
456 | alias_names = []
|
---|
457 | m.aliases.each do |other|
|
---|
458 | if other.viewer # won't be if the alias is private
|
---|
459 | alias_names << {
|
---|
460 | 'name' => other.name,
|
---|
461 | 'aref' => other.viewer.as_href(path)
|
---|
462 | }
|
---|
463 | end
|
---|
464 | end
|
---|
465 | unless alias_names.empty?
|
---|
466 | row["aka"] = alias_names
|
---|
467 | end
|
---|
468 |
|
---|
469 | if @options.inline_source
|
---|
470 | code = m.source_code
|
---|
471 | row["sourcecode"] = code if code
|
---|
472 | else
|
---|
473 | code = m.src_url
|
---|
474 | if code
|
---|
475 | row["codeurl"] = code
|
---|
476 | row["imgurl"] = m.img_url
|
---|
477 | end
|
---|
478 | end
|
---|
479 | res << row
|
---|
480 | end
|
---|
481 | end
|
---|
482 | if res.size > 0
|
---|
483 | outer << {
|
---|
484 | "type" => vis.to_s.capitalize,
|
---|
485 | "category" => singleton ? "Class" : "Instance",
|
---|
486 | "methods" => res
|
---|
487 | }
|
---|
488 | end
|
---|
489 | end
|
---|
490 | end
|
---|
491 | outer
|
---|
492 | end
|
---|
493 |
|
---|
494 | # Build the structured list of classes and modules contained
|
---|
495 | # in this context.
|
---|
496 |
|
---|
497 | def build_class_list(level, from, section, infile=nil)
|
---|
498 | res = ""
|
---|
499 | prefix = " ::" * level;
|
---|
500 |
|
---|
501 | from.modules.sort.each do |mod|
|
---|
502 | next unless mod.section == section
|
---|
503 | next if infile && !mod.defined_in?(infile)
|
---|
504 | if mod.document_self
|
---|
505 | res <<
|
---|
506 | prefix <<
|
---|
507 | "Module " <<
|
---|
508 | href(url(mod.viewer.path), "link", mod.full_name) <<
|
---|
509 | "<br />\n" <<
|
---|
510 | build_class_list(level + 1, mod, section, infile)
|
---|
511 | end
|
---|
512 | end
|
---|
513 |
|
---|
514 | from.classes.sort.each do |cls|
|
---|
515 | next unless cls.section == section
|
---|
516 | next if infile && !cls.defined_in?(infile)
|
---|
517 | if cls.document_self
|
---|
518 | res <<
|
---|
519 | prefix <<
|
---|
520 | "Class " <<
|
---|
521 | href(url(cls.viewer.path), "link", cls.full_name) <<
|
---|
522 | "<br />\n" <<
|
---|
523 | build_class_list(level + 1, cls, section, infile)
|
---|
524 | end
|
---|
525 | end
|
---|
526 |
|
---|
527 | res
|
---|
528 | end
|
---|
529 |
|
---|
530 | def url(target)
|
---|
531 | HTMLGenerator.gen_url(path, target)
|
---|
532 | end
|
---|
533 |
|
---|
534 | def aref_to(target)
|
---|
535 | if @options.all_one_file
|
---|
536 | "#" + target
|
---|
537 | else
|
---|
538 | url(target)
|
---|
539 | end
|
---|
540 | end
|
---|
541 |
|
---|
542 | def document_self
|
---|
543 | @context.document_self
|
---|
544 | end
|
---|
545 |
|
---|
546 | def diagram_reference(diagram)
|
---|
547 | res = diagram.gsub(/((?:src|href)=")(.*?)"/) {
|
---|
548 | $1 + url($2) + '"'
|
---|
549 | }
|
---|
550 | res
|
---|
551 | end
|
---|
552 |
|
---|
553 |
|
---|
554 | # Find a symbol in ourselves or our parent
|
---|
555 | def find_symbol(symbol, method=nil)
|
---|
556 | res = @context.find_symbol(symbol, method)
|
---|
557 | if res
|
---|
558 | res = res.viewer
|
---|
559 | end
|
---|
560 | res
|
---|
561 | end
|
---|
562 |
|
---|
563 | # create table of contents if we contain sections
|
---|
564 |
|
---|
565 | def add_table_of_sections
|
---|
566 | toc = []
|
---|
567 | @context.sections.each do |section|
|
---|
568 | if section.title
|
---|
569 | toc << {
|
---|
570 | 'secname' => section.title,
|
---|
571 | 'href' => section.sequence
|
---|
572 | }
|
---|
573 | end
|
---|
574 | end
|
---|
575 |
|
---|
576 | @values['toc'] = toc unless toc.empty?
|
---|
577 | end
|
---|
578 |
|
---|
579 |
|
---|
580 | end
|
---|
581 |
|
---|
582 | #####################################################################
|
---|
583 | #
|
---|
584 | # Wrap a ClassModule context
|
---|
585 |
|
---|
586 | class HtmlClass < ContextUser
|
---|
587 |
|
---|
588 | attr_reader :path
|
---|
589 |
|
---|
590 | def initialize(context, html_file, prefix, options)
|
---|
591 | super(context, options)
|
---|
592 |
|
---|
593 | @html_file = html_file
|
---|
594 | @is_module = context.is_module?
|
---|
595 | @values = {}
|
---|
596 |
|
---|
597 | context.viewer = self
|
---|
598 |
|
---|
599 | if options.all_one_file
|
---|
600 | @path = context.full_name
|
---|
601 | else
|
---|
602 | @path = http_url(context.full_name, prefix)
|
---|
603 | end
|
---|
604 |
|
---|
605 | collect_methods
|
---|
606 |
|
---|
607 | AllReferences.add(name, self)
|
---|
608 | end
|
---|
609 |
|
---|
610 | # return the relative file name to store this class in,
|
---|
611 | # which is also its url
|
---|
612 | def http_url(full_name, prefix)
|
---|
613 | path = full_name.dup
|
---|
614 | if path['<<']
|
---|
615 | path.gsub!(/<<\s*(\w*)/) { "from-#$1" }
|
---|
616 | end
|
---|
617 | File.join(prefix, path.split("::")) + ".html"
|
---|
618 | end
|
---|
619 |
|
---|
620 |
|
---|
621 | def name
|
---|
622 | @context.full_name
|
---|
623 | end
|
---|
624 |
|
---|
625 | def parent_name
|
---|
626 | @context.parent.full_name
|
---|
627 | end
|
---|
628 |
|
---|
629 | def index_name
|
---|
630 | name
|
---|
631 | end
|
---|
632 |
|
---|
633 | def write_on(f)
|
---|
634 | value_hash
|
---|
635 | template = TemplatePage.new(RDoc::Page::BODY,
|
---|
636 | RDoc::Page::CLASS_PAGE,
|
---|
637 | RDoc::Page::METHOD_LIST)
|
---|
638 | template.write_html_on(f, @values)
|
---|
639 | end
|
---|
640 |
|
---|
641 | def value_hash
|
---|
642 | class_attribute_values
|
---|
643 | add_table_of_sections
|
---|
644 |
|
---|
645 | @values["charset"] = @options.charset
|
---|
646 | @values["style_url"] = style_url(path, @options.css)
|
---|
647 |
|
---|
648 | d = markup(@context.comment)
|
---|
649 | @values["description"] = d unless d.empty?
|
---|
650 |
|
---|
651 | ml = build_method_summary_list
|
---|
652 | @values["methods"] = ml unless ml.empty?
|
---|
653 |
|
---|
654 | il = build_include_list(@context)
|
---|
655 | @values["includes"] = il unless il.empty?
|
---|
656 |
|
---|
657 | @values["sections"] = @context.sections.map do |section|
|
---|
658 |
|
---|
659 | secdata = {
|
---|
660 | "sectitle" => section.title,
|
---|
661 | "secsequence" => section.sequence,
|
---|
662 | "seccomment" => markup(section.comment)
|
---|
663 | }
|
---|
664 |
|
---|
665 | al = build_alias_summary_list(section)
|
---|
666 | secdata["aliases"] = al unless al.empty?
|
---|
667 |
|
---|
668 | co = build_constants_summary_list(section)
|
---|
669 | secdata["constants"] = co unless co.empty?
|
---|
670 |
|
---|
671 | al = build_attribute_list(section)
|
---|
672 | secdata["attributes"] = al unless al.empty?
|
---|
673 |
|
---|
674 | cl = build_class_list(0, @context, section)
|
---|
675 | secdata["classlist"] = cl unless cl.empty?
|
---|
676 |
|
---|
677 | mdl = build_method_detail_list(section)
|
---|
678 | secdata["method_list"] = mdl unless mdl.empty?
|
---|
679 |
|
---|
680 | secdata
|
---|
681 | end
|
---|
682 |
|
---|
683 | @values
|
---|
684 | end
|
---|
685 |
|
---|
686 | def build_attribute_list(section)
|
---|
687 | atts = @context.attributes.sort
|
---|
688 | res = []
|
---|
689 | atts.each do |att|
|
---|
690 | next unless att.section == section
|
---|
691 | if att.visibility == :public || att.visibility == :protected || @options.show_all
|
---|
692 | entry = {
|
---|
693 | "name" => CGI.escapeHTML(att.name),
|
---|
694 | "rw" => att.rw,
|
---|
695 | "a_desc" => markup(att.comment, true)
|
---|
696 | }
|
---|
697 | unless att.visibility == :public || att.visibility == :protected
|
---|
698 | entry["rw"] << "-"
|
---|
699 | end
|
---|
700 | res << entry
|
---|
701 | end
|
---|
702 | end
|
---|
703 | res
|
---|
704 | end
|
---|
705 |
|
---|
706 | def class_attribute_values
|
---|
707 | h_name = CGI.escapeHTML(name)
|
---|
708 |
|
---|
709 | @values["classmod"] = @is_module ? "Module" : "Class"
|
---|
710 | @values["title"] = "#{@values['classmod']}: #{h_name}"
|
---|
711 |
|
---|
712 | c = @context
|
---|
713 | c = c.parent while c and !c.diagram
|
---|
714 | if c && c.diagram
|
---|
715 | @values["diagram"] = diagram_reference(c.diagram)
|
---|
716 | end
|
---|
717 |
|
---|
718 | @values["full_name"] = h_name
|
---|
719 |
|
---|
720 | parent_class = @context.superclass
|
---|
721 |
|
---|
722 | if parent_class
|
---|
723 | @values["parent"] = CGI.escapeHTML(parent_class)
|
---|
724 |
|
---|
725 | if parent_name
|
---|
726 | lookup = parent_name + "::" + parent_class
|
---|
727 | else
|
---|
728 | lookup = parent_class
|
---|
729 | end
|
---|
730 |
|
---|
731 | parent_url = AllReferences[lookup] || AllReferences[parent_class]
|
---|
732 |
|
---|
733 | if parent_url and parent_url.document_self
|
---|
734 | @values["par_url"] = aref_to(parent_url.path)
|
---|
735 | end
|
---|
736 | end
|
---|
737 |
|
---|
738 | files = []
|
---|
739 | @context.in_files.each do |f|
|
---|
740 | res = {}
|
---|
741 | full_path = CGI.escapeHTML(f.file_absolute_name)
|
---|
742 |
|
---|
743 | res["full_path"] = full_path
|
---|
744 | res["full_path_url"] = aref_to(f.viewer.path) if f.document_self
|
---|
745 |
|
---|
746 | if @options.webcvs
|
---|
747 | res["cvsurl"] = cvs_url( @options.webcvs, full_path )
|
---|
748 | end
|
---|
749 |
|
---|
750 | files << res
|
---|
751 | end
|
---|
752 |
|
---|
753 | @values['infiles'] = files
|
---|
754 | end
|
---|
755 |
|
---|
756 | def <=>(other)
|
---|
757 | self.name <=> other.name
|
---|
758 | end
|
---|
759 |
|
---|
760 | end
|
---|
761 |
|
---|
762 | #####################################################################
|
---|
763 | #
|
---|
764 | # Handles the mapping of a file's information to HTML. In reality,
|
---|
765 | # a file corresponds to a +TopLevel+ object, containing modules,
|
---|
766 | # classes, and top-level methods. In theory it _could_ contain
|
---|
767 | # attributes and aliases, but we ignore these for now.
|
---|
768 |
|
---|
769 | class HtmlFile < ContextUser
|
---|
770 |
|
---|
771 | attr_reader :path
|
---|
772 | attr_reader :name
|
---|
773 |
|
---|
774 | def initialize(context, options, file_dir)
|
---|
775 | super(context, options)
|
---|
776 |
|
---|
777 | @values = {}
|
---|
778 |
|
---|
779 | if options.all_one_file
|
---|
780 | @path = filename_to_label
|
---|
781 | else
|
---|
782 | @path = http_url(file_dir)
|
---|
783 | end
|
---|
784 |
|
---|
785 | @name = @context.file_relative_name
|
---|
786 |
|
---|
787 | collect_methods
|
---|
788 | AllReferences.add(name, self)
|
---|
789 | context.viewer = self
|
---|
790 | end
|
---|
791 |
|
---|
792 | def http_url(file_dir)
|
---|
793 | File.join(file_dir, @context.file_relative_name.tr('.', '_')) +
|
---|
794 | ".html"
|
---|
795 | end
|
---|
796 |
|
---|
797 | def filename_to_label
|
---|
798 | @context.file_relative_name.gsub(/%|\/|\?|\#/) {|s| '%' + ("%x" % s[0]) }
|
---|
799 | end
|
---|
800 |
|
---|
801 | def index_name
|
---|
802 | name
|
---|
803 | end
|
---|
804 |
|
---|
805 | def parent_name
|
---|
806 | nil
|
---|
807 | end
|
---|
808 |
|
---|
809 | def value_hash
|
---|
810 | file_attribute_values
|
---|
811 | add_table_of_sections
|
---|
812 |
|
---|
813 | @values["charset"] = @options.charset
|
---|
814 | @values["href"] = path
|
---|
815 | @values["style_url"] = style_url(path, @options.css)
|
---|
816 |
|
---|
817 | if @context.comment
|
---|
818 | d = markup(@context.comment)
|
---|
819 | @values["description"] = d if d.size > 0
|
---|
820 | end
|
---|
821 |
|
---|
822 | ml = build_method_summary_list
|
---|
823 | @values["methods"] = ml unless ml.empty?
|
---|
824 |
|
---|
825 | il = build_include_list(@context)
|
---|
826 | @values["includes"] = il unless il.empty?
|
---|
827 |
|
---|
828 | rl = build_requires_list(@context)
|
---|
829 | @values["requires"] = rl unless rl.empty?
|
---|
830 |
|
---|
831 | if @options.promiscuous
|
---|
832 | file_context = nil
|
---|
833 | else
|
---|
834 | file_context = @context
|
---|
835 | end
|
---|
836 |
|
---|
837 |
|
---|
838 | @values["sections"] = @context.sections.map do |section|
|
---|
839 |
|
---|
840 | secdata = {
|
---|
841 | "sectitle" => section.title,
|
---|
842 | "secsequence" => section.sequence,
|
---|
843 | "seccomment" => markup(section.comment)
|
---|
844 | }
|
---|
845 |
|
---|
846 | cl = build_class_list(0, @context, section, file_context)
|
---|
847 | @values["classlist"] = cl unless cl.empty?
|
---|
848 |
|
---|
849 | mdl = build_method_detail_list(section)
|
---|
850 | secdata["method_list"] = mdl unless mdl.empty?
|
---|
851 |
|
---|
852 | al = build_alias_summary_list(section)
|
---|
853 | secdata["aliases"] = al unless al.empty?
|
---|
854 |
|
---|
855 | co = build_constants_summary_list(section)
|
---|
856 | @values["constants"] = co unless co.empty?
|
---|
857 |
|
---|
858 | secdata
|
---|
859 | end
|
---|
860 |
|
---|
861 | @values
|
---|
862 | end
|
---|
863 |
|
---|
864 | def write_on(f)
|
---|
865 | value_hash
|
---|
866 | template = TemplatePage.new(RDoc::Page::BODY,
|
---|
867 | RDoc::Page::FILE_PAGE,
|
---|
868 | RDoc::Page::METHOD_LIST)
|
---|
869 | template.write_html_on(f, @values)
|
---|
870 | end
|
---|
871 |
|
---|
872 | def file_attribute_values
|
---|
873 | full_path = @context.file_absolute_name
|
---|
874 | short_name = File.basename(full_path)
|
---|
875 |
|
---|
876 | @values["title"] = CGI.escapeHTML("File: #{short_name}")
|
---|
877 |
|
---|
878 | if @context.diagram
|
---|
879 | @values["diagram"] = diagram_reference(@context.diagram)
|
---|
880 | end
|
---|
881 |
|
---|
882 | @values["short_name"] = CGI.escapeHTML(short_name)
|
---|
883 | @values["full_path"] = CGI.escapeHTML(full_path)
|
---|
884 | @values["dtm_modified"] = @context.file_stat.mtime.to_s
|
---|
885 |
|
---|
886 | if @options.webcvs
|
---|
887 | @values["cvsurl"] = cvs_url( @options.webcvs, @values["full_path"] )
|
---|
888 | end
|
---|
889 | end
|
---|
890 |
|
---|
891 | def <=>(other)
|
---|
892 | self.name <=> other.name
|
---|
893 | end
|
---|
894 | end
|
---|
895 |
|
---|
896 | #####################################################################
|
---|
897 |
|
---|
898 | class HtmlMethod
|
---|
899 | include MarkUp
|
---|
900 |
|
---|
901 | attr_reader :context
|
---|
902 | attr_reader :src_url
|
---|
903 | attr_reader :img_url
|
---|
904 | attr_reader :source_code
|
---|
905 |
|
---|
906 | @@seq = "M000000"
|
---|
907 |
|
---|
908 | @@all_methods = []
|
---|
909 |
|
---|
910 | def HtmlMethod::reset
|
---|
911 | @@all_methods = []
|
---|
912 | end
|
---|
913 |
|
---|
914 | def initialize(context, html_class, options)
|
---|
915 | @context = context
|
---|
916 | @html_class = html_class
|
---|
917 | @options = options
|
---|
918 | @@seq = @@seq.succ
|
---|
919 | @seq = @@seq
|
---|
920 | @@all_methods << self
|
---|
921 |
|
---|
922 | context.viewer = self
|
---|
923 |
|
---|
924 | if (ts = @context.token_stream)
|
---|
925 | @source_code = markup_code(ts)
|
---|
926 | unless @options.inline_source
|
---|
927 | @src_url = create_source_code_file(@source_code)
|
---|
928 | @img_url = HTMLGenerator.gen_url(path, 'source.png')
|
---|
929 | end
|
---|
930 | end
|
---|
931 |
|
---|
932 | AllReferences.add(name, self)
|
---|
933 | end
|
---|
934 |
|
---|
935 | # return a reference to outselves to be used as an href=
|
---|
936 | # the form depends on whether we're all in one file
|
---|
937 | # or in multiple files
|
---|
938 |
|
---|
939 | def as_href(from_path)
|
---|
940 | if @options.all_one_file
|
---|
941 | "#" + path
|
---|
942 | else
|
---|
943 | HTMLGenerator.gen_url(from_path, path)
|
---|
944 | end
|
---|
945 | end
|
---|
946 |
|
---|
947 | def name
|
---|
948 | @context.name
|
---|
949 | end
|
---|
950 |
|
---|
951 | def section
|
---|
952 | @context.section
|
---|
953 | end
|
---|
954 |
|
---|
955 | def index_name
|
---|
956 | "#{@context.name} (#{@html_class.name})"
|
---|
957 | end
|
---|
958 |
|
---|
959 | def parent_name
|
---|
960 | if @context.parent.parent
|
---|
961 | @context.parent.parent.full_name
|
---|
962 | else
|
---|
963 | nil
|
---|
964 | end
|
---|
965 | end
|
---|
966 |
|
---|
967 | def aref
|
---|
968 | @seq
|
---|
969 | end
|
---|
970 |
|
---|
971 | def path
|
---|
972 | if @options.all_one_file
|
---|
973 | aref
|
---|
974 | else
|
---|
975 | @html_class.path + "#" + aref
|
---|
976 | end
|
---|
977 | end
|
---|
978 |
|
---|
979 | def description
|
---|
980 | markup(@context.comment)
|
---|
981 | end
|
---|
982 |
|
---|
983 | def visibility
|
---|
984 | @context.visibility
|
---|
985 | end
|
---|
986 |
|
---|
987 | def singleton
|
---|
988 | @context.singleton
|
---|
989 | end
|
---|
990 |
|
---|
991 | def call_seq
|
---|
992 | cs = @context.call_seq
|
---|
993 | if cs
|
---|
994 | cs.gsub(/\n/, "<br />\n")
|
---|
995 | else
|
---|
996 | nil
|
---|
997 | end
|
---|
998 | end
|
---|
999 |
|
---|
1000 | def params
|
---|
1001 | # params coming from a call-seq in 'C' will start with the
|
---|
1002 | # method name
|
---|
1003 | p = @context.params
|
---|
1004 | if p !~ /^\w/
|
---|
1005 | p = @context.params.gsub(/\s*\#.*/, '')
|
---|
1006 | p = p.tr("\n", " ").squeeze(" ")
|
---|
1007 | p = "(" + p + ")" unless p[0] == ?(
|
---|
1008 |
|
---|
1009 | if (block = @context.block_params)
|
---|
1010 | # If this method has explicit block parameters, remove any
|
---|
1011 | # explicit &block
|
---|
1012 |
|
---|
1013 | p.sub!(/,?\s*&\w+/, '')
|
---|
1014 |
|
---|
1015 | block.gsub!(/\s*\#.*/, '')
|
---|
1016 | block = block.tr("\n", " ").squeeze(" ")
|
---|
1017 | if block[0] == ?(
|
---|
1018 | block.sub!(/^\(/, '').sub!(/\)/, '')
|
---|
1019 | end
|
---|
1020 | p << " {|#{block.strip}| ...}"
|
---|
1021 | end
|
---|
1022 | end
|
---|
1023 | CGI.escapeHTML(p)
|
---|
1024 | end
|
---|
1025 |
|
---|
1026 | def create_source_code_file(code_body)
|
---|
1027 | meth_path = @html_class.path.sub(/\.html$/, '.src')
|
---|
1028 | File.makedirs(meth_path)
|
---|
1029 | file_path = File.join(meth_path, @seq) + ".html"
|
---|
1030 |
|
---|
1031 | template = TemplatePage.new(RDoc::Page::SRC_PAGE)
|
---|
1032 | File.open(file_path, "w") do |f|
|
---|
1033 | values = {
|
---|
1034 | 'title' => CGI.escapeHTML(index_name),
|
---|
1035 | 'code' => code_body,
|
---|
1036 | 'style_url' => style_url(file_path, @options.css),
|
---|
1037 | 'charset' => @options.charset
|
---|
1038 | }
|
---|
1039 | template.write_html_on(f, values)
|
---|
1040 | end
|
---|
1041 | HTMLGenerator.gen_url(path, file_path)
|
---|
1042 | end
|
---|
1043 |
|
---|
1044 | def HtmlMethod.all_methods
|
---|
1045 | @@all_methods
|
---|
1046 | end
|
---|
1047 |
|
---|
1048 | def <=>(other)
|
---|
1049 | @context <=> other.context
|
---|
1050 | end
|
---|
1051 |
|
---|
1052 | ##
|
---|
1053 | # Given a sequence of source tokens, mark up the source code
|
---|
1054 | # to make it look purty.
|
---|
1055 |
|
---|
1056 |
|
---|
1057 | def markup_code(tokens)
|
---|
1058 | src = ""
|
---|
1059 | tokens.each do |t|
|
---|
1060 | next unless t
|
---|
1061 | # p t.class
|
---|
1062 | # style = STYLE_MAP[t.class]
|
---|
1063 | style = case t
|
---|
1064 | when RubyToken::TkCONSTANT then "ruby-constant"
|
---|
1065 | when RubyToken::TkKW then "ruby-keyword kw"
|
---|
1066 | when RubyToken::TkIVAR then "ruby-ivar"
|
---|
1067 | when RubyToken::TkOp then "ruby-operator"
|
---|
1068 | when RubyToken::TkId then "ruby-identifier"
|
---|
1069 | when RubyToken::TkNode then "ruby-node"
|
---|
1070 | when RubyToken::TkCOMMENT then "ruby-comment cmt"
|
---|
1071 | when RubyToken::TkREGEXP then "ruby-regexp re"
|
---|
1072 | when RubyToken::TkSTRING then "ruby-value str"
|
---|
1073 | when RubyToken::TkVal then "ruby-value"
|
---|
1074 | else
|
---|
1075 | nil
|
---|
1076 | end
|
---|
1077 |
|
---|
1078 | text = CGI.escapeHTML(t.text)
|
---|
1079 |
|
---|
1080 | if style
|
---|
1081 | src << "<span class=\"#{style}\">#{text}</span>"
|
---|
1082 | else
|
---|
1083 | src << text
|
---|
1084 | end
|
---|
1085 | end
|
---|
1086 |
|
---|
1087 | add_line_numbers(src) if Options.instance.include_line_numbers
|
---|
1088 | src
|
---|
1089 | end
|
---|
1090 |
|
---|
1091 | # we rely on the fact that the first line of a source code
|
---|
1092 | # listing has
|
---|
1093 | # # File xxxxx, line dddd
|
---|
1094 |
|
---|
1095 | def add_line_numbers(src)
|
---|
1096 | if src =~ /\A.*, line (\d+)/
|
---|
1097 | first = $1.to_i - 1
|
---|
1098 | last = first + src.count("\n")
|
---|
1099 | size = last.to_s.length
|
---|
1100 | real_fmt = "%#{size}d: "
|
---|
1101 | fmt = " " * (size+2)
|
---|
1102 | src.gsub!(/^/) do
|
---|
1103 | res = sprintf(fmt, first)
|
---|
1104 | first += 1
|
---|
1105 | fmt = real_fmt
|
---|
1106 | res
|
---|
1107 | end
|
---|
1108 | end
|
---|
1109 | end
|
---|
1110 |
|
---|
1111 | def document_self
|
---|
1112 | @context.document_self
|
---|
1113 | end
|
---|
1114 |
|
---|
1115 | def aliases
|
---|
1116 | @context.aliases
|
---|
1117 | end
|
---|
1118 |
|
---|
1119 | def find_symbol(symbol, method=nil)
|
---|
1120 | res = @context.parent.find_symbol(symbol, method)
|
---|
1121 | if res
|
---|
1122 | res = res.viewer
|
---|
1123 | end
|
---|
1124 | res
|
---|
1125 | end
|
---|
1126 | end
|
---|
1127 |
|
---|
1128 | #####################################################################
|
---|
1129 |
|
---|
1130 | class HTMLGenerator
|
---|
1131 |
|
---|
1132 | include MarkUp
|
---|
1133 |
|
---|
1134 | ##
|
---|
1135 | # convert a target url to one that is relative to a given
|
---|
1136 | # path
|
---|
1137 |
|
---|
1138 | def HTMLGenerator.gen_url(path, target)
|
---|
1139 | from = File.dirname(path)
|
---|
1140 | to, to_file = File.split(target)
|
---|
1141 |
|
---|
1142 | from = from.split("/")
|
---|
1143 | to = to.split("/")
|
---|
1144 |
|
---|
1145 | while from.size > 0 and to.size > 0 and from[0] == to[0]
|
---|
1146 | from.shift
|
---|
1147 | to.shift
|
---|
1148 | end
|
---|
1149 |
|
---|
1150 | from.fill("..")
|
---|
1151 | from.concat(to)
|
---|
1152 | from << to_file
|
---|
1153 | File.join(*from)
|
---|
1154 | end
|
---|
1155 |
|
---|
1156 | # Generators may need to return specific subclasses depending
|
---|
1157 | # on the options they are passed. Because of this
|
---|
1158 | # we create them using a factory
|
---|
1159 |
|
---|
1160 | def HTMLGenerator.for(options)
|
---|
1161 | AllReferences::reset
|
---|
1162 | HtmlMethod::reset
|
---|
1163 |
|
---|
1164 | if options.all_one_file
|
---|
1165 | HTMLGeneratorInOne.new(options)
|
---|
1166 | else
|
---|
1167 | HTMLGenerator.new(options)
|
---|
1168 | end
|
---|
1169 | end
|
---|
1170 |
|
---|
1171 | class <<self
|
---|
1172 | protected :new
|
---|
1173 | end
|
---|
1174 |
|
---|
1175 | # Set up a new HTML generator. Basically all we do here is load
|
---|
1176 | # up the correct output temlate
|
---|
1177 |
|
---|
1178 | def initialize(options) #:not-new:
|
---|
1179 | @options = options
|
---|
1180 | load_html_template
|
---|
1181 | end
|
---|
1182 |
|
---|
1183 |
|
---|
1184 | ##
|
---|
1185 | # Build the initial indices and output objects
|
---|
1186 | # based on an array of TopLevel objects containing
|
---|
1187 | # the extracted information.
|
---|
1188 |
|
---|
1189 | def generate(toplevels)
|
---|
1190 | @toplevels = toplevels
|
---|
1191 | @files = []
|
---|
1192 | @classes = []
|
---|
1193 |
|
---|
1194 | write_style_sheet
|
---|
1195 | gen_sub_directories()
|
---|
1196 | build_indices
|
---|
1197 | generate_html
|
---|
1198 | end
|
---|
1199 |
|
---|
1200 | private
|
---|
1201 |
|
---|
1202 | ##
|
---|
1203 | # Load up the HTML template specified in the options.
|
---|
1204 | # If the template name contains a slash, use it literally
|
---|
1205 | #
|
---|
1206 | def load_html_template
|
---|
1207 | template = @options.template
|
---|
1208 | unless template =~ %r{/|\\}
|
---|
1209 | template = File.join("rdoc/generators/template",
|
---|
1210 | @options.generator.key, template)
|
---|
1211 | end
|
---|
1212 | require template
|
---|
1213 | extend RDoc::Page
|
---|
1214 | rescue LoadError
|
---|
1215 | $stderr.puts "Could not find HTML template '#{template}'"
|
---|
1216 | exit 99
|
---|
1217 | end
|
---|
1218 |
|
---|
1219 | ##
|
---|
1220 | # Write out the style sheet used by the main frames
|
---|
1221 | #
|
---|
1222 |
|
---|
1223 | def write_style_sheet
|
---|
1224 | template = TemplatePage.new(RDoc::Page::STYLE)
|
---|
1225 | unless @options.css
|
---|
1226 | File.open(CSS_NAME, "w") do |f|
|
---|
1227 | values = { "fonts" => RDoc::Page::FONTS }
|
---|
1228 | template.write_html_on(f, values)
|
---|
1229 | end
|
---|
1230 | end
|
---|
1231 | end
|
---|
1232 |
|
---|
1233 | ##
|
---|
1234 | # See the comments at the top for a description of the
|
---|
1235 | # directory structure
|
---|
1236 |
|
---|
1237 | def gen_sub_directories
|
---|
1238 | File.makedirs(FILE_DIR, CLASS_DIR)
|
---|
1239 | rescue
|
---|
1240 | $stderr.puts $!.message
|
---|
1241 | exit 1
|
---|
1242 | end
|
---|
1243 |
|
---|
1244 | ##
|
---|
1245 | # Generate:
|
---|
1246 | #
|
---|
1247 | # * a list of HtmlFile objects for each TopLevel object.
|
---|
1248 | # * a list of HtmlClass objects for each first level
|
---|
1249 | # class or module in the TopLevel objects
|
---|
1250 | # * a complete list of all hyperlinkable terms (file,
|
---|
1251 | # class, module, and method names)
|
---|
1252 |
|
---|
1253 | def build_indices
|
---|
1254 |
|
---|
1255 | @toplevels.each do |toplevel|
|
---|
1256 | @files << HtmlFile.new(toplevel, @options, FILE_DIR)
|
---|
1257 | end
|
---|
1258 |
|
---|
1259 | RDoc::TopLevel.all_classes_and_modules.each do |cls|
|
---|
1260 | build_class_list(cls, @files[0], CLASS_DIR)
|
---|
1261 | end
|
---|
1262 | end
|
---|
1263 |
|
---|
1264 | def build_class_list(from, html_file, class_dir)
|
---|
1265 | @classes << HtmlClass.new(from, html_file, class_dir, @options)
|
---|
1266 | from.each_classmodule do |mod|
|
---|
1267 | build_class_list(mod, html_file, class_dir)
|
---|
1268 | end
|
---|
1269 | end
|
---|
1270 |
|
---|
1271 | ##
|
---|
1272 | # Generate all the HTML
|
---|
1273 | #
|
---|
1274 | def generate_html
|
---|
1275 | # the individual descriptions for files and classes
|
---|
1276 | gen_into(@files)
|
---|
1277 | gen_into(@classes)
|
---|
1278 | # and the index files
|
---|
1279 | gen_file_index
|
---|
1280 | gen_class_index
|
---|
1281 | gen_method_index
|
---|
1282 | gen_main_index
|
---|
1283 |
|
---|
1284 | # this method is defined in the template file
|
---|
1285 | write_extra_pages if defined? write_extra_pages
|
---|
1286 | end
|
---|
1287 |
|
---|
1288 | def gen_into(list)
|
---|
1289 | list.each do |item|
|
---|
1290 | if item.document_self
|
---|
1291 | op_file = item.path
|
---|
1292 | File.makedirs(File.dirname(op_file))
|
---|
1293 | File.open(op_file, "w") { |file| item.write_on(file) }
|
---|
1294 | end
|
---|
1295 | end
|
---|
1296 |
|
---|
1297 | end
|
---|
1298 |
|
---|
1299 | def gen_file_index
|
---|
1300 | gen_an_index(@files, 'Files',
|
---|
1301 | RDoc::Page::FILE_INDEX,
|
---|
1302 | "fr_file_index.html")
|
---|
1303 | end
|
---|
1304 |
|
---|
1305 | def gen_class_index
|
---|
1306 | gen_an_index(@classes, 'Classes',
|
---|
1307 | RDoc::Page::CLASS_INDEX,
|
---|
1308 | "fr_class_index.html")
|
---|
1309 | end
|
---|
1310 |
|
---|
1311 | def gen_method_index
|
---|
1312 | gen_an_index(HtmlMethod.all_methods, 'Methods',
|
---|
1313 | RDoc::Page::METHOD_INDEX,
|
---|
1314 | "fr_method_index.html")
|
---|
1315 | end
|
---|
1316 |
|
---|
1317 |
|
---|
1318 | def gen_an_index(collection, title, template, filename)
|
---|
1319 | template = TemplatePage.new(RDoc::Page::FR_INDEX_BODY, template)
|
---|
1320 | res = []
|
---|
1321 | collection.sort.each do |f|
|
---|
1322 | if f.document_self
|
---|
1323 | res << { "href" => f.path, "name" => f.index_name }
|
---|
1324 | end
|
---|
1325 | end
|
---|
1326 |
|
---|
1327 | values = {
|
---|
1328 | "entries" => res,
|
---|
1329 | 'list_title' => CGI.escapeHTML(title),
|
---|
1330 | 'index_url' => main_url,
|
---|
1331 | 'charset' => @options.charset,
|
---|
1332 | 'style_url' => style_url('', @options.css),
|
---|
1333 | }
|
---|
1334 |
|
---|
1335 | File.open(filename, "w") do |f|
|
---|
1336 | template.write_html_on(f, values)
|
---|
1337 | end
|
---|
1338 | end
|
---|
1339 |
|
---|
1340 | # The main index page is mostly a template frameset, but includes
|
---|
1341 | # the initial page. If the <tt>--main</tt> option was given,
|
---|
1342 | # we use this as our main page, otherwise we use the
|
---|
1343 | # first file specified on the command line.
|
---|
1344 |
|
---|
1345 | def gen_main_index
|
---|
1346 | template = TemplatePage.new(RDoc::Page::INDEX)
|
---|
1347 | File.open("index.html", "w") do |f|
|
---|
1348 | values = {
|
---|
1349 | "initial_page" => main_url,
|
---|
1350 | 'title' => CGI.escapeHTML(@options.title),
|
---|
1351 | 'charset' => @options.charset
|
---|
1352 | }
|
---|
1353 | if @options.inline_source
|
---|
1354 | values['inline_source'] = true
|
---|
1355 | end
|
---|
1356 | template.write_html_on(f, values)
|
---|
1357 | end
|
---|
1358 | end
|
---|
1359 |
|
---|
1360 | # return the url of the main page
|
---|
1361 | def main_url
|
---|
1362 | main_page = @options.main_page
|
---|
1363 | ref = nil
|
---|
1364 | if main_page
|
---|
1365 | ref = AllReferences[main_page]
|
---|
1366 | if ref
|
---|
1367 | ref = ref.path
|
---|
1368 | else
|
---|
1369 | $stderr.puts "Could not find main page #{main_page}"
|
---|
1370 | end
|
---|
1371 | end
|
---|
1372 |
|
---|
1373 | unless ref
|
---|
1374 | for file in @files
|
---|
1375 | if file.document_self
|
---|
1376 | ref = file.path
|
---|
1377 | break
|
---|
1378 | end
|
---|
1379 | end
|
---|
1380 | end
|
---|
1381 |
|
---|
1382 | unless ref
|
---|
1383 | $stderr.puts "Couldn't find anything to document"
|
---|
1384 | $stderr.puts "Perhaps you've used :stopdoc: in all classes"
|
---|
1385 | exit(1)
|
---|
1386 | end
|
---|
1387 |
|
---|
1388 | ref
|
---|
1389 | end
|
---|
1390 |
|
---|
1391 |
|
---|
1392 | end
|
---|
1393 |
|
---|
1394 |
|
---|
1395 | ######################################################################
|
---|
1396 |
|
---|
1397 |
|
---|
1398 | class HTMLGeneratorInOne < HTMLGenerator
|
---|
1399 |
|
---|
1400 | def initialize(*args)
|
---|
1401 | super
|
---|
1402 | end
|
---|
1403 |
|
---|
1404 | ##
|
---|
1405 | # Build the initial indices and output objects
|
---|
1406 | # based on an array of TopLevel objects containing
|
---|
1407 | # the extracted information.
|
---|
1408 |
|
---|
1409 | def generate(info)
|
---|
1410 | @toplevels = info
|
---|
1411 | @files = []
|
---|
1412 | @classes = []
|
---|
1413 | @hyperlinks = {}
|
---|
1414 |
|
---|
1415 | build_indices
|
---|
1416 | generate_xml
|
---|
1417 | end
|
---|
1418 |
|
---|
1419 |
|
---|
1420 | ##
|
---|
1421 | # Generate:
|
---|
1422 | #
|
---|
1423 | # * a list of HtmlFile objects for each TopLevel object.
|
---|
1424 | # * a list of HtmlClass objects for each first level
|
---|
1425 | # class or module in the TopLevel objects
|
---|
1426 | # * a complete list of all hyperlinkable terms (file,
|
---|
1427 | # class, module, and method names)
|
---|
1428 |
|
---|
1429 | def build_indices
|
---|
1430 |
|
---|
1431 | @toplevels.each do |toplevel|
|
---|
1432 | @files << HtmlFile.new(toplevel, @options, FILE_DIR)
|
---|
1433 | end
|
---|
1434 |
|
---|
1435 | RDoc::TopLevel.all_classes_and_modules.each do |cls|
|
---|
1436 | build_class_list(cls, @files[0], CLASS_DIR)
|
---|
1437 | end
|
---|
1438 | end
|
---|
1439 |
|
---|
1440 | def build_class_list(from, html_file, class_dir)
|
---|
1441 | @classes << HtmlClass.new(from, html_file, class_dir, @options)
|
---|
1442 | from.each_classmodule do |mod|
|
---|
1443 | build_class_list(mod, html_file, class_dir)
|
---|
1444 | end
|
---|
1445 | end
|
---|
1446 |
|
---|
1447 | ##
|
---|
1448 | # Generate all the HTML. For the one-file case, we generate
|
---|
1449 | # all the information in to one big hash
|
---|
1450 | #
|
---|
1451 | def generate_xml
|
---|
1452 | values = {
|
---|
1453 | 'charset' => @options.charset,
|
---|
1454 | 'files' => gen_into(@files),
|
---|
1455 | 'classes' => gen_into(@classes),
|
---|
1456 | 'title' => CGI.escapeHTML(@options.title),
|
---|
1457 | }
|
---|
1458 |
|
---|
1459 | # this method is defined in the template file
|
---|
1460 | write_extra_pages if defined? write_extra_pages
|
---|
1461 |
|
---|
1462 | template = TemplatePage.new(RDoc::Page::ONE_PAGE)
|
---|
1463 |
|
---|
1464 | if @options.op_name
|
---|
1465 | opfile = File.open(@options.op_name, "w")
|
---|
1466 | else
|
---|
1467 | opfile = $stdout
|
---|
1468 | end
|
---|
1469 | template.write_html_on(opfile, values)
|
---|
1470 | end
|
---|
1471 |
|
---|
1472 | def gen_into(list)
|
---|
1473 | res = []
|
---|
1474 | list.each do |item|
|
---|
1475 | res << item.value_hash
|
---|
1476 | end
|
---|
1477 | res
|
---|
1478 | end
|
---|
1479 |
|
---|
1480 | def gen_file_index
|
---|
1481 | gen_an_index(@files, 'Files')
|
---|
1482 | end
|
---|
1483 |
|
---|
1484 | def gen_class_index
|
---|
1485 | gen_an_index(@classes, 'Classes')
|
---|
1486 | end
|
---|
1487 |
|
---|
1488 | def gen_method_index
|
---|
1489 | gen_an_index(HtmlMethod.all_methods, 'Methods')
|
---|
1490 | end
|
---|
1491 |
|
---|
1492 |
|
---|
1493 | def gen_an_index(collection, title)
|
---|
1494 | res = []
|
---|
1495 | collection.sort.each do |f|
|
---|
1496 | if f.document_self
|
---|
1497 | res << { "href" => f.path, "name" => f.index_name }
|
---|
1498 | end
|
---|
1499 | end
|
---|
1500 |
|
---|
1501 | return {
|
---|
1502 | "entries" => res,
|
---|
1503 | 'list_title' => title,
|
---|
1504 | 'index_url' => main_url,
|
---|
1505 | }
|
---|
1506 | end
|
---|
1507 |
|
---|
1508 | end
|
---|
1509 | end
|
---|