kotovalexarian-likes-github/ruby--ruby
1
0
Fork 0
mirror of https://github.com/ruby/ruby.git synced 2022-11-09 12:17:21 -05:00
Code Releases Activity

Clean up comments and whitespace in RDoc generators

Browse source 
git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@14919 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
This commit is contained in:
drbrain 2008-01-07 00:42:03 +00:00
parent ee6abe3252
commit b0f13cfebe
4 changed files with 248 additions and 262 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

55
lib/rdoc/generators/chm_generator.rb
View file

@ -6,12 +6,13 @@ module Generators
HHC_PATH = "c:/Program Files/HTML Help Workshop/hhc.exe" HHC_PATH = "c:/Program Files/HTML Help Workshop/hhc.exe"
##
# Standard generator factory # Standard generator factory
def CHMGenerator.for(options) def CHMGenerator.for(options)
CHMGenerator.new(options) CHMGenerator.new(options)
end end
def initialize(*args) def initialize(*args)
super super
@op_name = @options.op_name || "rdoc" @op_name = @options.op_name || "rdoc"
@ -22,32 +23,35 @@ module Generators
stat = File.stat(HHC_PATH) stat = File.stat(HHC_PATH)
rescue rescue
$stderr << $stderr <<
"\n.chm output generation requires that Microsoft's Html Help\n" << "\n.chm output generation requires that Microsoft's Html Help\n" <<
"Workshop is installed. RDoc looks for it in:\n\n " << "Workshop is installed. RDoc looks for it in:\n\n " <<
HHC_PATH << HHC_PATH <<
"\n\nYou can download a copy for free from:\n\n" << "\n\nYou can download a copy for free from:\n\n" <<
" http://msdn.microsoft.com/library/default.asp?" << " http://msdn.microsoft.com/library/default.asp?" <<
"url=/library/en-us/htmlhelp/html/hwMicrosoftHTMLHelpDownloads.asp\n\n" "url=/library/en-us/htmlhelp/html/hwMicrosoftHTMLHelpDownloads.asp\n\n"
exit 99 exit 99
end end
# Generate the html as normal, then wrap it ##
# in a help project # Generate the html as normal, then wrap it in a help project
def generate(info) def generate(info)
super super
@project_name = @op_name + ".hhp" @project_name = @op_name + ".hhp"
create_help_project create_help_project
end end
# The project contains the project file, a table of contents ##
# and an index # The project contains the project file, a table of contents and an index
def create_help_project def create_help_project
create_project_file create_project_file
create_contents_and_index create_contents_and_index
compile_project compile_project
end end
##
# The project file links together all the various # The project file links together all the various
# files that go to make up the help. # files that go to make up the help.
@ -56,16 +60,17 @@ module Generators
values = { "title" => @options.title, "opname" => @op_name } values = { "title" => @options.title, "opname" => @op_name }
files = [] files = []
@files.each do |f| @files.each do |f|
files << { "html_file_name" => f.path } files << { "html_file_name" => f.path }
end end
values['all_html_files'] = files values['all_html_files'] = files
File.open(@project_name, "w") do |f| File.open(@project_name, "w") do |f|
template.write_html_on(f, values) template.write_html_on(f, values)
end end
end end
##
# The contents is a list of all files and modules. # The contents is a list of all files and modules.
# For each we include as sub-entries the list # For each we include as sub-entries the list
# of methods they contain. As we build the contents # of methods they contain. As we build the contents
@ -76,37 +81,39 @@ module Generators
index = [] index = []
(@files+@classes).sort.each do |entry| (@files+@classes).sort.each do |entry|
content_entry = { "c_name" => entry.name, "ref" => entry.path } content_entry = { "c_name" => entry.name, "ref" => entry.path }
index << { "name" => entry.name, "aref" => entry.path } index << { "name" => entry.name, "aref" => entry.path }
internals = [] internals = []
methods = entry.build_method_summary_list(entry.path) methods = entry.build_method_summary_list(entry.path)
content_entry["methods"] = methods unless methods.empty? content_entry["methods"] = methods unless methods.empty?
contents << content_entry contents << content_entry
index.concat methods index.concat methods
end end
values = { "contents" => contents } values = { "contents" => contents }
template = TemplatePage.new(RDoc::Page::CONTENTS) template = TemplatePage.new(RDoc::Page::CONTENTS)
File.open("contents.hhc", "w") do |f| File.open("contents.hhc", "w") do |f|
template.write_html_on(f, values) template.write_html_on(f, values)
end end
values = { "index" => index } values = { "index" => index }
template = TemplatePage.new(RDoc::Page::CHM_INDEX) template = TemplatePage.new(RDoc::Page::CHM_INDEX)
File.open("index.hhk", "w") do |f| File.open("index.hhk", "w") do |f|
template.write_html_on(f, values) template.write_html_on(f, values)
end end
end end
##
# Invoke the windows help compiler to compiler the project # Invoke the windows help compiler to compiler the project
def compile_project def compile_project
system(HHC_PATH, @project_name) system(HHC_PATH, @project_name)
end end
end end
end end

357
lib/rdoc/generators/html_generator.rb
View file

@ -1,39 +1,3 @@
# We're responsible for generating all the HTML files
# from the object tree defined in code_objects.rb. We
# generate:
#
# [files] an html file for each input file given. These
# input files appear as objects of class
# TopLevel
#
# [classes] an html file for each class or module encountered.
# These classes are not grouped by file: if a file
# contains four classes, we'll generate an html
# file for the file itself, and four html files
# for the individual classes.
#
# [indices] we generate three indices for files, classes,
# and methods. These are displayed in a browser
# like window with three index panes across the
# top and the selected description below
#
# Method descriptions appear in whatever entity (file, class,
# or module) that contains them.
#
# We generate files in a structure below a specified subdirectory,
# normally +doc+.
#
# opdir
# |
# |___ files
# | |__ per file summaries
# |
# |___ classes
# |__ per class/module descriptions
#
# HTML is generated using the Template class.
#
require 'fileutils' require 'fileutils'
require 'rdoc/options' require 'rdoc/options'
@ -44,24 +8,32 @@ require 'cgi'
module Generators module Generators
# Name of sub-direcories that hold file and class/module descriptions ##
# Name of sub-direcory that holds file descriptions
FILE_DIR = "files" FILE_DIR = "files"
##
# Name of sub-direcory that holds class descriptions
CLASS_DIR = "classes" CLASS_DIR = "classes"
##
# Name of the RDoc CSS file
CSS_NAME = "rdoc-style.css" CSS_NAME = "rdoc-style.css"
## ##
# Build a hash of all items that can be cross-referenced. # Build a hash of all items that can be cross-referenced.
# This is used when we output required and included names: # This is used when we output required and included names:
# if the names appear in this hash, we can generate # if the names appear in this hash, we can generate
# an html cross reference to the appropriate description. # an html cross reference to the appropriate description.
# We also use this when parsing comment blocks: any decorated # We also use this when parsing comment blocks: any decorated
# words matching an entry in this list are hyperlinked. # words matching an entry in this list are hyperlinked.
class AllReferences class AllReferences
@@refs = {} @@refs = {}
def AllReferences::reset def AllReferences::reset
@@refs = {} @@refs = {}
end end
@ -79,7 +51,6 @@ module Generators
end end
end end
## ##
# Subclass of the SM::ToHtml class that supports looking # Subclass of the SM::ToHtml class that supports looking
# up words in the AllReferences list. Those that are # up words in the AllReferences list. Those that are
@ -87,6 +58,8 @@ module Generators
# be hyperlinked # be hyperlinked
class HyperlinkHtml < SM::ToHtml class HyperlinkHtml < SM::ToHtml
##
# We need to record the html path of our caller so we can generate # We need to record the html path of our caller so we can generate
# correct relative paths for any hyperlinks that we find # correct relative paths for any hyperlinks that we find
def initialize(from_path, context) def initialize(from_path, context)
@ -98,6 +71,7 @@ module Generators
@context = context @context = context
end end
##
# We're invoked when any text matches the CROSSREF pattern # We're invoked when any text matches the CROSSREF pattern
# (defined in MarkUp). If we fine the corresponding reference, # (defined in MarkUp). If we fine the corresponding reference,
# generate a hyperlink. If the name we're looking for contains # generate a hyperlink. If the name we're looking for contains
@ -134,9 +108,10 @@ module Generators
end end
end end
##
# Generate a hyperlink for url, labeled with text. Handle the # Generate a hyperlink for url, labeled with text. Handle the
# special cases for img: and link: described under handle_special_HYPEDLINK # special cases for img: and link: described under handle_special_HYPEDLINK
def gen_url(url, text) def gen_url(url, text)
if url =~ /([A-Za-z]+):(.*)/ if url =~ /([A-Za-z]+):(.*)/
type = $1 type = $1
@ -155,7 +130,7 @@ module Generators
end end
end end
if (type == "http" || type == "link") && if (type == "http" || type == "link") &&
url =~ /\.(gif|png|jpg|jpeg|bmp)$/ url =~ /\.(gif|png|jpg|jpeg|bmp)$/
"<img src=\"#{url}\" />" "<img src=\"#{url}\" />"
@ -164,6 +139,7 @@ module Generators
end end
end end
##
# And we're invoked with a potential external hyperlink mailto: # And we're invoked with a potential external hyperlink mailto:
# just gets inserted. http: links are checked to see if they # just gets inserted. http: links are checked to see if they
# reference an image. If so, that image gets inserted using an # reference an image. If so, that image gets inserted using an
@ -176,14 +152,14 @@ module Generators
gen_url(url, url) gen_url(url, url)
end end
# HEre's a hypedlink where the label is different to the URL ##
# Here's a hypedlink where the label is different to the URL
# <label>[url] # <label>[url]
#
def handle_special_TIDYLINK(special) def handle_special_TIDYLINK(special)
text = special.text text = special.text
# unless text =~ /(\S+)\[(.*?)\]/ # unless text =~ /(\S+)\[(.*?)\]/
unless text =~ /\{(.*?)\}\[(.*?)\]/ or text =~ /(\S+)\[(.*?)\]/ unless text =~ /\{(.*?)\}\[(.*?)\]/ or text =~ /(\S+)\[(.*?)\]/
return text return text
end end
label = $1 label = $1
@ -193,15 +169,12 @@ module Generators
end end
##
#####################################################################
#
# Handle common markup tasks for the various Html classes # Handle common markup tasks for the various Html classes
#
module MarkUp module MarkUp
##
# Convert a string in markup format into HTML. We keep a cached # Convert a string in markup format into HTML. We keep a cached
# SimpleMarkup object lying around after the first time we're # SimpleMarkup object lying around after the first time we're
# called per object. # called per object.
@ -217,9 +190,9 @@ module Generators
| \#\w+(\([.\w\*\/\+\-\=\<\>]+\))? # meth(**) (for operator in Fortran95) | \#\w+(\([.\w\*\/\+\-\=\<\>]+\))? # meth(**) (for operator in Fortran95)
| \b([A-Z]\w*(::\w+)*[.\#]\w+) # A::B.meth | \b([A-Z]\w*(::\w+)*[.\#]\w+) # A::B.meth
| \b([A-Z]\w+(::\w+)*) # A::B.. | \b([A-Z]\w+(::\w+)*) # A::B..
| \#\w+[!?=]? # #meth_name | \#\w+[!?=]? # #meth_name
| \b\w+([_\/\.]+\w+)*[!?=]? # meth_name | \b\w+([_\/\.]+\w+)*[!?=]? # meth_name
)/x, )/x,
:CROSSREF) :CROSSREF)
# external hyperlinks # external hyperlinks
@ -251,6 +224,7 @@ module Generators
res res
end end
##
# Qualify a stylesheet URL; if if +css_name+ does not begin with '/' or # Qualify a stylesheet URL; if if +css_name+ does not begin with '/' or
# 'http[s]://', prepend a prefix relative to +path+. Otherwise, return it # 'http[s]://', prepend a prefix relative to +path+. Otherwise, return it
# unmodified. # unmodified.
@ -265,6 +239,7 @@ module Generators
end end
end end
##
# Build a webcvs URL with the given 'url' argument. URLs with a '%s' in them # Build a webcvs URL with the given 'url' argument. URLs with a '%s' in them
# get the file's path sprintfed into them; otherwise they're just catenated # get the file's path sprintfed into them; otherwise they're just catenated
# together. # together.
@ -276,34 +251,35 @@ module Generators
return url + full_path return url + full_path
end end
end end
end end
##
#####################################################################
#
# A Context is built by the parser to represent a container: contexts # A Context is built by the parser to represent a container: contexts
# hold classes, modules, methods, require lists and include lists. # hold classes, modules, methods, require lists and include lists.
# ClassModule and TopLevel are the context objects we process here # ClassModule and TopLevel are the context objects we process here
#
class ContextUser class ContextUser
include MarkUp include MarkUp
attr_reader :context attr_reader :context
def initialize(context, options) def initialize(context, options)
@context = context @context = context
@options = options @options = options
end end
##
# convenience method to build a hyperlink # convenience method to build a hyperlink
def href(link, cls, name) def href(link, cls, name)
%{<a href="#{link}" class="#{cls}">#{name}</a>} #" %{<a href="#{link}" class="#{cls}">#{name}</a>} #"
end end
# return a reference to outselves to be used as an href= ##
# the form depends on whether we're all in one file # Returns a reference to outselves to be used as an href= the form depends
# or in multiple files # on whether we're all in one file or in multiple files
def as_href(from_path) def as_href(from_path)
if @options.all_one_file if @options.all_one_file
@ -313,10 +289,11 @@ module Generators
end end
end end
# Create a list of HtmlMethod objects for each method ##
# in the corresponding context object. If the @options.show_all # Create a list of HtmlMethod objects for each method in the corresponding
# variable is set (corresponding to the <tt>--all</tt> option, # context object. If the @options.show_all variable is set (corresponding
# we include all methods, otherwise just the public ones. # to the <tt>--all</tt> option, we include all methods, otherwise just the
# public ones.
def collect_methods def collect_methods
list = @context.method_list list = @context.method_list
@ -326,23 +303,26 @@ module Generators
@methods = list.collect {|m| HtmlMethod.new(m, self, @options) } @methods = list.collect {|m| HtmlMethod.new(m, self, @options) }
end end
##
# Build a summary list of all the methods in this context # Build a summary list of all the methods in this context
def build_method_summary_list(path_prefix="") def build_method_summary_list(path_prefix="")
collect_methods unless @methods collect_methods unless @methods
meths = @methods.sort meths = @methods.sort
res = [] res = []
meths.each do |meth| meths.each do |meth|
res << { res << {
"name" => CGI.escapeHTML(meth.name), "name" => CGI.escapeHTML(meth.name),
"aref" => "#{path_prefix}\##{meth.aref}" "aref" => "#{path_prefix}\##{meth.aref}"
} }
end end
res res
end end
##
# Build a list of aliases for which we couldn't find a # Build a list of aliases for which we couldn't find a
# corresponding method # corresponding method
def build_alias_summary_list(section) def build_alias_summary_list(section)
values = [] values = []
@context.aliases.each do |al| @context.aliases.each do |al|
@ -358,8 +338,10 @@ module Generators
end end
values values
end end
##
# Build a list of constants # Build a list of constants
def build_constants_summary_list(section) def build_constants_summary_list(section)
values = [] values = []
@context.constants.each do |co| @context.constants.each do |co|
@ -373,7 +355,7 @@ module Generators
end end
values values
end end
def build_requires_list(context) def build_requires_list(context)
potentially_referenced_list(context.requires) {|fn| [fn + ".rb"] } potentially_referenced_list(context.requires) {|fn| [fn + ".rb"] }
end end
@ -382,6 +364,7 @@ module Generators
potentially_referenced_list(context.includes) potentially_referenced_list(context.includes)
end end
##
# Build a list from an array of <i>Htmlxxx</i> items. Look up each # Build a list from an array of <i>Htmlxxx</i> items. Look up each
# in the AllReferences hash: if we find a corresponding entry, # in the AllReferences hash: if we find a corresponding entry,
# we generate a hyperlink to it, otherwise just output the name. # we generate a hyperlink to it, otherwise just output the name.
@ -394,12 +377,12 @@ module Generators
def potentially_referenced_list(array) def potentially_referenced_list(array)
res = [] res = []
array.each do |i| array.each do |i|
ref = AllReferences[i.name] ref = AllReferences[i.name]
# if !ref # if !ref
# container = @context.parent # container = @context.parent
# while !ref && container # while !ref && container
# name = container.name + "::" + i.name # name = container.name + "::" + i.name
# ref = AllReferences[name] # ref = AllReferences[name]
# container = container.parent # container = container.parent
# end # end
# end # end
@ -424,6 +407,7 @@ module Generators
res res
end end
##
# Build an array of arrays of method details. The outer array has up # Build an array of arrays of method details. The outer array has up
# to six entries, public, private, and protected for both class # to six entries, public, private, and protected for both class
# methods, the other for instance methods. The inner arrays contain # methods, the other for instance methods. The inner arrays contain
@ -434,12 +418,12 @@ module Generators
methods = @methods.sort methods = @methods.sort
for singleton in [true, false] for singleton in [true, false]
for vis in [ :public, :protected, :private ] for vis in [ :public, :protected, :private ]
res = [] res = []
methods.each do |m| methods.each do |m|
if m.section == section and if m.section == section and
m.document_self and m.document_self and
m.visibility == vis and m.visibility == vis and
m.singleton == singleton m.singleton == singleton
row = {} row = {}
if m.call_seq if m.call_seq
@ -459,7 +443,7 @@ module Generators
alias_names << { alias_names << {
'name' => other.name, 'name' => other.name,
'aref' => other.viewer.as_href(path) 'aref' => other.viewer.as_href(path)
} }
end end
end end
unless alias_names.empty? unless alias_names.empty?
@ -479,7 +463,7 @@ module Generators
res << row res << row
end end
end end
if res.size > 0 if res.size > 0
outer << { outer << {
"type" => vis.to_s.capitalize, "type" => vis.to_s.capitalize,
"category" => singleton ? "Class" : "Instance", "category" => singleton ? "Class" : "Instance",
@ -491,8 +475,9 @@ module Generators
outer outer
end end
##
# Build the structured list of classes and modules contained # Build the structured list of classes and modules contained
# in this context. # in this context.
def build_class_list(level, from, section, infile=nil) def build_class_list(level, from, section, infile=nil)
res = "" res = ""
@ -502,7 +487,7 @@ module Generators
next unless mod.section == section next unless mod.section == section
next if infile && !mod.defined_in?(infile) next if infile && !mod.defined_in?(infile)
if mod.document_self if mod.document_self
res << res <<
prefix << prefix <<
"Module " << "Module " <<
href(url(mod.viewer.path), "link", mod.full_name) << href(url(mod.viewer.path), "link", mod.full_name) <<
@ -516,7 +501,7 @@ module Generators
next if infile && !cls.defined_in?(infile) next if infile && !cls.defined_in?(infile)
if cls.document_self if cls.document_self
res << res <<
prefix << prefix <<
"Class " << "Class " <<
href(url(cls.viewer.path), "link", cls.full_name) << href(url(cls.viewer.path), "link", cls.full_name) <<
"<br />\n" << "<br />\n" <<
@ -526,7 +511,7 @@ module Generators
res res
end end
def url(target) def url(target)
HTMLGenerator.gen_url(path, target) HTMLGenerator.gen_url(path, target)
end end
@ -550,8 +535,9 @@ module Generators
res res
end end
##
# Find a symbol in ourselves or our parent # Find a symbol in ourselves or our parent
def find_symbol(symbol, method=nil) def find_symbol(symbol, method=nil)
res = @context.find_symbol(symbol, method) res = @context.find_symbol(symbol, method)
if res if res
@ -560,8 +546,9 @@ module Generators
res res
end end
##
# create table of contents if we contain sections # create table of contents if we contain sections
def add_table_of_sections def add_table_of_sections
toc = [] toc = []
@context.sections.each do |section| @context.sections.each do |section|
@ -572,15 +559,13 @@ module Generators
} }
end end
end end
@values['toc'] = toc unless toc.empty? @values['toc'] = toc unless toc.empty?
end end
end end
##################################################################### ##
#
# Wrap a ClassModule context # Wrap a ClassModule context
class HtmlClass < ContextUser class HtmlClass < ContextUser
@ -607,8 +592,10 @@ module Generators
AllReferences.add(name, self) AllReferences.add(name, self)
end end
# return the relative file name to store this class in, ##
# which is also its url # Returns the relative file name to store this class in, which is also its
# url
def http_url(full_name, prefix) def http_url(full_name, prefix)
path = full_name.dup path = full_name.dup
if path['<<'] if path['<<']
@ -617,7 +604,6 @@ module Generators
File.join(prefix, path.split("::")) + ".html" File.join(prefix, path.split("::")) + ".html"
end end
def name def name
@context.full_name @context.full_name
end end
@ -664,16 +650,16 @@ module Generators
al = build_alias_summary_list(section) al = build_alias_summary_list(section)
secdata["aliases"] = al unless al.empty? secdata["aliases"] = al unless al.empty?
co = build_constants_summary_list(section) co = build_constants_summary_list(section)
secdata["constants"] = co unless co.empty? secdata["constants"] = co unless co.empty?
al = build_attribute_list(section) al = build_attribute_list(section)
secdata["attributes"] = al unless al.empty? secdata["attributes"] = al unless al.empty?
cl = build_class_list(0, @context, section) cl = build_class_list(0, @context, section)
secdata["classlist"] = cl unless cl.empty? secdata["classlist"] = cl unless cl.empty?
mdl = build_method_detail_list(section) mdl = build_method_detail_list(section)
secdata["method_list"] = mdl unless mdl.empty? secdata["method_list"] = mdl unless mdl.empty?
@ -690,8 +676,8 @@ module Generators
next unless att.section == section next unless att.section == section
if att.visibility == :public || att.visibility == :protected || @options.show_all if att.visibility == :public || att.visibility == :protected || @options.show_all
entry = { entry = {
"name" => CGI.escapeHTML(att.name), "name" => CGI.escapeHTML(att.name),
"rw" => att.rw, "rw" => att.rw,
"a_desc" => markup(att.comment, true) "a_desc" => markup(att.comment, true)
} }
unless att.visibility == :public || att.visibility == :protected unless att.visibility == :public || att.visibility == :protected
@ -720,19 +706,19 @@ module Generators
parent_class = @context.superclass parent_class = @context.superclass
if parent_class if parent_class
@values["parent"] = CGI.escapeHTML(parent_class) @values["parent"] = CGI.escapeHTML(parent_class)
if parent_name if parent_name
lookup = parent_name + "::" + parent_class lookup = parent_name + "::" + parent_class
else else
lookup = parent_class lookup = parent_class
end end
parent_url = AllReferences[lookup] || AllReferences[parent_class] parent_url = AllReferences[lookup] || AllReferences[parent_class]
if parent_url and parent_url.document_self if parent_url and parent_url.document_self
@values["par_url"] = aref_to(parent_url.path) @values["par_url"] = aref_to(parent_url.path)
end end
end end
files = [] files = []
@ -759,8 +745,7 @@ module Generators
end end
##################################################################### ##
#
# Handles the mapping of a file's information to HTML. In reality, # Handles the mapping of a file's information to HTML. In reality,
# a file corresponds to a +TopLevel+ object, containing modules, # a file corresponds to a +TopLevel+ object, containing modules,
# classes, and top-level methods. In theory it _could_ contain # classes, and top-level methods. In theory it _could_ contain
@ -851,16 +836,16 @@ module Generators
al = build_alias_summary_list(section) al = build_alias_summary_list(section)
secdata["aliases"] = al unless al.empty? secdata["aliases"] = al unless al.empty?
co = build_constants_summary_list(section) co = build_constants_summary_list(section)
@values["constants"] = co unless co.empty? @values["constants"] = co unless co.empty?
secdata secdata
end end
@values @values
end end
def write_on(f) def write_on(f)
value_hash value_hash
template = TemplatePage.new(RDoc::Page::BODY, template = TemplatePage.new(RDoc::Page::BODY,
@ -872,7 +857,7 @@ module Generators
def file_attribute_values def file_attribute_values
full_path = @context.file_absolute_name full_path = @context.file_absolute_name
short_name = File.basename(full_path) short_name = File.basename(full_path)
@values["title"] = CGI.escapeHTML("File: #{short_name}") @values["title"] = CGI.escapeHTML("File: #{short_name}")
if @context.diagram if @context.diagram
@ -891,11 +876,13 @@ module Generators
def <=>(other) def <=>(other)
self.name <=> other.name self.name <=> other.name
end end
end end
##################################################################### ##
class HtmlMethod class HtmlMethod
include MarkUp include MarkUp
attr_reader :context attr_reader :context
@ -931,10 +918,10 @@ module Generators
AllReferences.add(name, self) AllReferences.add(name, self)
end end
# return a reference to outselves to be used as an href= ##
# the form depends on whether we're all in one file # Returns a reference to outselves to be used as an href= the form depends
# or in multiple files # on whether we're all in one file or in multiple files
def as_href(from_path) def as_href(from_path)
if @options.all_one_file if @options.all_one_file
@ -970,9 +957,9 @@ module Generators
def path def path
if @options.all_one_file if @options.all_one_file
aref aref
else else
@html_class.path + "#" + aref @html_class.path + "#" + aref
end end
end end
@ -1005,7 +992,7 @@ module Generators
p = @context.params.gsub(/\s*\#.*/, '') p = @context.params.gsub(/\s*\#.*/, '')
p = p.tr("\n", " ").squeeze(" ") p = p.tr("\n", " ").squeeze(" ")
p = "(" + p + ")" unless p[0] == ?( p = "(" + p + ")" unless p[0] == ?(
if (block = @context.block_params) if (block = @context.block_params)
# If this method has explicit block parameters, remove any # If this method has explicit block parameters, remove any
# explicit &block # explicit &block
@ -1022,7 +1009,7 @@ module Generators
end end
CGI.escapeHTML(p) CGI.escapeHTML(p)
end end
def create_source_code_file(code_body) def create_source_code_file(code_body)
meth_path = @html_class.path.sub(/\.html$/, '.src') meth_path = @html_class.path.sub(/\.html$/, '.src')
FileUtils.mkdir_p(meth_path) FileUtils.mkdir_p(meth_path)
@ -1053,7 +1040,6 @@ module Generators
# Given a sequence of source tokens, mark up the source code # Given a sequence of source tokens, mark up the source code
# to make it look purty. # to make it look purty.
def markup_code(tokens) def markup_code(tokens)
src = "" src = ""
tokens.each do |t| tokens.each do |t|
@ -1088,8 +1074,8 @@ module Generators
src src
end end
# we rely on the fact that the first line of a source code ##
# listing has # We rely on the fact that the first line of a source code listing has
# # File xxxxx, line dddd # # File xxxxx, line dddd
def add_line_numbers(src) def add_line_numbers(src)
@ -1100,7 +1086,7 @@ module Generators
real_fmt = "%#{size}d: " real_fmt = "%#{size}d: "
fmt = " " * (size+2) fmt = " " * (size+2)
src.gsub!(/^/) do src.gsub!(/^/) do
res = sprintf(fmt, first) res = sprintf(fmt, first)
first += 1 first += 1
fmt = real_fmt fmt = real_fmt
res res
@ -1123,39 +1109,73 @@ module Generators
end end
res res
end end
end end
##################################################################### ##
# We're responsible for generating all the HTML files
# from the object tree defined in code_objects.rb. We
# generate:
#
# [files] an html file for each input file given. These
# input files appear as objects of class
# TopLevel
#
# [classes] an html file for each class or module encountered.
# These classes are not grouped by file: if a file
# contains four classes, we'll generate an html
# file for the file itself, and four html files
# for the individual classes.
#
# [indices] we generate three indices for files, classes,
# and methods. These are displayed in a browser
# like window with three index panes across the
# top and the selected description below
#
# Method descriptions appear in whatever entity (file, class,
# or module) that contains them.
#
# We generate files in a structure below a specified subdirectory,
# normally +doc+.
#
# opdir
# |
# |___ files
# | |__ per file summaries
# |
# |___ classes
# |__ per class/module descriptions
#
# HTML is generated using the Template class.
class HTMLGenerator class HTMLGenerator
include MarkUp include MarkUp
## ##
# convert a target url to one that is relative to a given # Converts a target url to one that is relative to a given path
# path
def HTMLGenerator.gen_url(path, target) def HTMLGenerator.gen_url(path, target)
from = File.dirname(path) from = File.dirname(path)
to, to_file = File.split(target) to, to_file = File.split(target)
from = from.split("/") from = from.split("/")
to = to.split("/") to = to.split("/")
while from.size > 0 and to.size > 0 and from[0] == to[0] while from.size > 0 and to.size > 0 and from[0] == to[0]
from.shift from.shift
to.shift to.shift
end end
from.fill("..") from.fill("..")
from.concat(to) from.concat(to)
from << to_file from << to_file
File.join(*from) File.join(*from)
end end
# Generators may need to return specific subclasses depending ##
# on the options they are passed. Because of this # Generators may need to return specific subclasses depending on the
# we create them using a factory # options they are passed. Because of this we create them using a factory
def HTMLGenerator.for(options) def HTMLGenerator.for(options)
AllReferences::reset AllReferences::reset
@ -1172,19 +1192,19 @@ module Generators
protected :new protected :new
end end
# Set up a new HTML generator. Basically all we do here is load ##
# up the correct output temlate # Set up a new HTML generator. Basically all we do here is load up the
# correct output temlate
def initialize(options) #:not-new: def initialize(options) #:not-new:
@options = options @options = options
load_html_template load_html_template
end end
## ##
# Build the initial indices and output objects # Build the initial indices and output objects
# based on an array of TopLevel objects containing # based on an array of TopLevel objects containing
# the extracted information. # the extracted information.
def generate(toplevels) def generate(toplevels)
@toplevels = toplevels @toplevels = toplevels
@ -1202,7 +1222,7 @@ module Generators
## ##
# Load up the HTML template specified in the options. # Load up the HTML template specified in the options.
# If the template name contains a slash, use it literally # If the template name contains a slash, use it literally
#
def load_html_template def load_html_template
template = @options.template template = @options.template
unless template =~ %r{/|\\} unless template =~ %r{/|\\}
@ -1218,8 +1238,7 @@ module Generators
## ##
# Write out the style sheet used by the main frames # Write out the style sheet used by the main frames
#
def write_style_sheet def write_style_sheet
template = TemplatePage.new(RDoc::Page::STYLE) template = TemplatePage.new(RDoc::Page::STYLE)
unless @options.css unless @options.css
@ -1231,13 +1250,12 @@ module Generators
end end
## ##
# See the comments at the top for a description of the # See the comments at the top for a description of the directory structure
# directory structure
def gen_sub_directories def gen_sub_directories
FileUtils.mkdir_p(FILE_DIR) FileUtils.mkdir_p(FILE_DIR)
FileUtils.mkdir_p(CLASS_DIR) FileUtils.mkdir_p(CLASS_DIR)
rescue rescue
$stderr.puts $!.message $stderr.puts $!.message
exit 1 exit 1
end end
@ -1271,7 +1289,7 @@ module Generators
## ##
# Generate all the HTML # Generate all the HTML
#
def generate_html def generate_html
# the individual descriptions for files and classes # the individual descriptions for files and classes
gen_into(@files) gen_into(@files)
@ -1281,7 +1299,7 @@ module Generators
gen_class_index gen_class_index
gen_method_index gen_method_index
gen_main_index gen_main_index
# this method is defined in the template file # this method is defined in the template file
write_extra_pages if defined? write_extra_pages write_extra_pages if defined? write_extra_pages
end end
@ -1298,8 +1316,8 @@ module Generators
end end
def gen_file_index def gen_file_index
gen_an_index(@files, 'Files', gen_an_index(@files, 'Files',
RDoc::Page::FILE_INDEX, RDoc::Page::FILE_INDEX,
"fr_file_index.html") "fr_file_index.html")
end end
@ -1310,12 +1328,11 @@ module Generators
end end
def gen_method_index def gen_method_index
gen_an_index(HtmlMethod.all_methods, 'Methods', gen_an_index(HtmlMethod.all_methods, 'Methods',
RDoc::Page::METHOD_INDEX, RDoc::Page::METHOD_INDEX,
"fr_method_index.html") "fr_method_index.html")
end end
def gen_an_index(collection, title, template, filename) def gen_an_index(collection, title, template, filename)
template = TemplatePage.new(RDoc::Page::FR_INDEX_BODY, template) template = TemplatePage.new(RDoc::Page::FR_INDEX_BODY, template)
res = [] res = []
@ -1338,10 +1355,11 @@ module Generators
end end
end end
# The main index page is mostly a template frameset, but includes ##
# the initial page. If the <tt>--main</tt> option was given, # The main index page is mostly a template frameset, but includes the
# we use this as our main page, otherwise we use the # initial page. If the <tt>--main</tt> option was given, we use this as
# first file specified on the command line. # our main page, otherwise we use the first file specified on the command
# line.
def gen_main_index def gen_main_index
template = TemplatePage.new(RDoc::Page::INDEX) template = TemplatePage.new(RDoc::Page::INDEX)
@ -1358,7 +1376,9 @@ module Generators
end end
end end
# return the url of the main page ##
# Returns the url of the main page
def main_url def main_url
main_page = @options.main_page main_page = @options.main_page
ref = nil ref = nil
@ -1374,7 +1394,7 @@ module Generators
unless ref unless ref
for file in @files for file in @files
if file.document_self if file.document_self
ref = file.path ref = file.path
break break
end end
end end
@ -1389,13 +1409,8 @@ module Generators
ref ref
end end
end end
######################################################################
class HTMLGeneratorInOne < HTMLGenerator class HTMLGeneratorInOne < HTMLGenerator
def initialize(*args) def initialize(*args)
@ -1405,7 +1420,7 @@ module Generators
## ##
# Build the initial indices and output objects # Build the initial indices and output objects
# based on an array of TopLevel objects containing # based on an array of TopLevel objects containing
# the extracted information. # the extracted information.
def generate(info) def generate(info)
@toplevels = info @toplevels = info
@ -1417,7 +1432,6 @@ module Generators
generate_xml generate_xml
end end
## ##
# Generate: # Generate:
# #
@ -1448,15 +1462,15 @@ module Generators
## ##
# Generate all the HTML. For the one-file case, we generate # Generate all the HTML. For the one-file case, we generate
# all the information in to one big hash # all the information in to one big hash
#
def generate_xml def generate_xml
values = { values = {
'charset' => @options.charset, 'charset' => @options.charset,
'files' => gen_into(@files), 'files' => gen_into(@files),
'classes' => gen_into(@classes), 'classes' => gen_into(@classes),
'title' => CGI.escapeHTML(@options.title), 'title' => CGI.escapeHTML(@options.title),
} }
# this method is defined in the template file # this method is defined in the template file
write_extra_pages if defined? write_extra_pages write_extra_pages if defined? write_extra_pages
@ -1490,7 +1504,6 @@ module Generators
gen_an_index(HtmlMethod.all_methods, 'Methods') gen_an_index(HtmlMethod.all_methods, 'Methods')
end end
def gen_an_index(collection, title) def gen_an_index(collection, title)
res = [] res = []
collection.sort.each do |f| collection.sort.each do |f|
@ -1507,4 +1520,6 @@ module Generators
end end
end end
end end

82
lib/rdoc/generators/ri_generator.rb
View file

@ -1,39 +1,3 @@
# We're responsible for generating all the HTML files
# from the object tree defined in code_objects.rb. We
# generate:
#
# [files] an html file for each input file given. These
# input files appear as objects of class
# TopLevel
#
# [classes] an html file for each class or module encountered.
# These classes are not grouped by file: if a file
# contains four classes, we'll generate an html
# file for the file itself, and four html files
# for the individual classes.
#
# [indices] we generate three indices for files, classes,
# and methods. These are displayed in a browser
# like window with three index panes across the
# top and the selected description below
#
# Method descriptions appear in whatever entity (file, class,
# or module) that contains them.
#
# We generate files in a structure below a specified subdirectory,
# normally +doc+.
#
# opdir
# |
# |___ files
# | |__ per file summaries
# |
# |___ classes
# |__ per class/module descriptions
#
# HTML is generated using the Template class.
#
require 'rdoc/options' require 'rdoc/options'
require 'rdoc/template' require 'rdoc/template'
require 'rdoc/markup/simple_markup' require 'rdoc/markup/simple_markup'
@ -47,12 +11,11 @@ require 'rdoc/ri/ri_descriptions'
module Generators module Generators
class RIGenerator class RIGenerator
# Generators may need to return specific subclasses depending ##
# on the options they are passed. Because of this # Generators may need to return specific subclasses depending on the
# we create them using a factory # options they are passed. Because of this we create them using a factory
def RIGenerator.for(options) def RIGenerator.for(options)
new(options) new(options)
@ -62,8 +25,9 @@ module Generators
protected :new protected :new
end end
# Set up a new HTML generator. Basically all we do here is load ##
# up the correct output temlate # Set up a new HTML generator. Basically all we do here is load up the
# correct output temlate
def initialize(options) #:not-new: def initialize(options) #:not-new:
@options = options @options = options
@ -72,11 +36,9 @@ module Generators
@to_flow = SM::ToFlow.new @to_flow = SM::ToFlow.new
end end
## ##
# Build the initial indices and output objects # Build the initial indices and output objects based on an array of
# based on an array of TopLevel objects containing # TopLevel objects containing the extracted information.
# the extracted information.
def generate(toplevels) def generate(toplevels)
RDoc::TopLevel.all_classes_and_modules.each do |cls| RDoc::TopLevel.all_classes_and_modules.each do |cls|
@ -163,8 +125,8 @@ module Generators
private private
# return a list of class and instance methods that we'll be ##
# documenting # Returns a list of class and instance methods that we'll be documenting
def method_list(cls) def method_list(cls)
list = cls.method_list list = cls.method_list
@ -185,17 +147,17 @@ module Generators
end end
return c,i return c,i
end end
def params_of(method) def params_of(method)
if method.call_seq if method.call_seq
method.call_seq method.call_seq
else else
params = method.params || "" params = method.params || ""
p = params.gsub(/\s*\#.*/, '') p = params.gsub(/\s*\#.*/, '')
p = p.tr("\n", " ").squeeze(" ") p = p.tr("\n", " ").squeeze(" ")
p = "(" + p + ")" unless p[0] == ?( p = "(" + p + ")" unless p[0] == ?(
if (block = method.block_params) if (block = method.block_params)
block.gsub!(/\s*\#.*/, '') block.gsub!(/\s*\#.*/, '')
block = block.tr("\n", " ").squeeze(" ") block = block.tr("\n", " ").squeeze(" ")
@ -213,7 +175,7 @@ module Generators
# Convert leading comment markers to spaces, but only # Convert leading comment markers to spaces, but only
# if all non-blank lines have them # if all non-blank lines have them
if comment =~ /^(?>\s*)[^\#]/ if comment =~ /^(?>\s*)[^\#]/
content = comment content = comment
else else
@ -222,12 +184,11 @@ module Generators
@markup.convert(content, @to_flow) @markup.convert(content, @to_flow)
end end
##
# By default we replace existing classes with the # By default we replace existing classes with the same name. If the
# same name. If the --merge option was given, we instead # --merge option was given, we instead merge this definition into an
# merge this definition into an existing class. We add # existing class. We add our methods, aliases, etc to that class, but do
# our methods, aliases, etc to that class, but do not # not change the class's description.
# change the class's description.
def update_or_replace(cls_desc) def update_or_replace(cls_desc)
old_cls = nil old_cls = nil
@ -242,7 +203,7 @@ module Generators
$stderr.puts "documentation. This file references a class or " $stderr.puts "documentation. This file references a class or "
$stderr.puts "module called #{cls_desc.name} which I don't" $stderr.puts "module called #{cls_desc.name} which I don't"
$stderr.puts "have existing documentation for." $stderr.puts "have existing documentation for."
$stderr.puts $stderr.puts
$stderr.puts "Perhaps you need to generate its documentation first" $stderr.puts "Perhaps you need to generate its documentation first"
exit 1 exit 1
else else
@ -262,5 +223,8 @@ module Generators
@ri_writer.add_class(old_desc) @ri_writer.add_class(old_desc)
end end
end end
end end
end end

16
lib/rdoc/generators/xml_generator.rb
View file

@ -1,4 +1,3 @@
require 'rdoc/options' require 'rdoc/options'
require 'rdoc/markup/simple_markup' require 'rdoc/markup/simple_markup'
require 'rdoc/markup/simple_markup/to_html' require 'rdoc/markup/simple_markup/to_html'
@ -6,16 +5,18 @@ require 'rdoc/generators/html_generator'
module Generators module Generators
##
# Generate XML output as one big file # Generate XML output as one big file
class XMLGenerator < HTMLGenerator class XMLGenerator < HTMLGenerator
##
# Standard generator factory # Standard generator factory
def XMLGenerator.for(options) def XMLGenerator.for(options)
XMLGenerator.new(options) XMLGenerator.new(options)
end end
def initialize(*args) def initialize(*args)
super super
end end
@ -23,7 +24,7 @@ module Generators
## ##
# Build the initial indices and output objects # Build the initial indices and output objects
# based on an array of TopLevel objects containing # based on an array of TopLevel objects containing
# the extracted information. # the extracted information.
def generate(info) def generate(info)
@info = info @info = info
@ -35,7 +36,6 @@ module Generators
generate_xml generate_xml
end end
## ##
# Generate: # Generate:
# #
@ -66,14 +66,14 @@ module Generators
## ##
# Generate all the HTML. For the one-file case, we generate # Generate all the HTML. For the one-file case, we generate
# all the information in to one big hash # all the information in to one big hash
#
def generate_xml def generate_xml
values = { values = {
'charset' => @options.charset, 'charset' => @options.charset,
'files' => gen_into(@files), 'files' => gen_into(@files),
'classes' => gen_into(@classes) 'classes' => gen_into(@classes)
} }
# this method is defined in the template file # this method is defined in the template file
write_extra_pages if defined? write_extra_pages write_extra_pages if defined? write_extra_pages
@ -107,7 +107,6 @@ module Generators
gen_an_index(HtmlMethod.all_methods, 'Methods') gen_an_index(HtmlMethod.all_methods, 'Methods')
end end
def gen_an_index(collection, title) def gen_an_index(collection, title)
res = [] res = []
collection.sort.each do |f| collection.sort.each do |f|
@ -126,3 +125,4 @@ module Generators
end end
end end