mirror of
https://github.com/ruby/ruby.git
synced 2022-11-09 12:17:21 -05:00
Clean up comments and whitespace in RDoc generators
git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@14919 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
This commit is contained in:
parent
ee6abe3252
commit
b0f13cfebe
4 changed files with 248 additions and 262 deletions
|
@ -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"
|
||||||
|
@ -32,22 +33,25 @@ module Generators
|
||||||
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.
|
||||||
|
|
||||||
|
@ -66,6 +70,7 @@ module Generators
|
||||||
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
|
||||||
|
@ -101,12 +106,14 @@ module Generators
|
||||||
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
|
||||||
|
|
||||||
|
|
|
@ -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,12 +8,20 @@ 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"
|
||||||
CLASS_DIR = "classes"
|
|
||||||
CSS_NAME = "rdoc-style.css"
|
|
||||||
|
|
||||||
|
##
|
||||||
|
# Name of sub-direcory that holds class descriptions
|
||||||
|
|
||||||
|
CLASS_DIR = "classes"
|
||||||
|
|
||||||
|
##
|
||||||
|
# Name of the RDoc CSS file
|
||||||
|
|
||||||
|
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.
|
||||||
|
@ -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
|
||||||
|
@ -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,9 +152,9 @@ 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
|
||||||
|
@ -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.
|
||||||
|
@ -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,15 +251,14 @@ 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
|
||||||
|
@ -296,14 +270,16 @@ module Generators
|
||||||
@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,7 +303,9 @@ 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
|
||||||
|
@ -340,9 +319,10 @@ module Generators
|
||||||
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|
|
||||||
|
@ -359,7 +339,9 @@ module Generators
|
||||||
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|
|
||||||
|
@ -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.
|
||||||
|
@ -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
|
||||||
|
@ -491,6 +475,7 @@ 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.
|
||||||
|
|
||||||
|
@ -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,6 +546,7 @@ 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
|
||||||
|
@ -576,11 +563,9 @@ module Generators
|
||||||
@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
|
||||||
|
@ -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
|
||||||
|
@ -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
|
||||||
|
@ -932,9 +919,9 @@ 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
|
||||||
|
@ -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)
|
||||||
|
@ -1123,17 +1109,51 @@ 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)
|
||||||
|
@ -1153,9 +1173,9 @@ module Generators
|
||||||
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,15 +1192,15 @@ 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
|
||||||
|
@ -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,7 +1238,6 @@ 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)
|
||||||
|
@ -1231,8 +1250,7 @@ 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)
|
||||||
|
@ -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)
|
||||||
|
@ -1315,7 +1333,6 @@ module Generators
|
||||||
"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
|
||||||
|
@ -1389,13 +1409,8 @@ module Generators
|
||||||
ref
|
ref
|
||||||
end
|
end
|
||||||
|
|
||||||
|
|
||||||
end
|
end
|
||||||
|
|
||||||
|
|
||||||
######################################################################
|
|
||||||
|
|
||||||
|
|
||||||
class HTMLGeneratorInOne < HTMLGenerator
|
class HTMLGeneratorInOne < HTMLGenerator
|
||||||
|
|
||||||
def initialize(*args)
|
def initialize(*args)
|
||||||
|
@ -1417,7 +1432,6 @@ module Generators
|
||||||
generate_xml
|
generate_xml
|
||||||
end
|
end
|
||||||
|
|
||||||
|
|
||||||
##
|
##
|
||||||
# Generate:
|
# Generate:
|
||||||
#
|
#
|
||||||
|
@ -1448,7 +1462,7 @@ 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,
|
||||||
|
@ -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
|
||||||
|
|
||||||
|
|
|
@ -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
|
||||||
|
@ -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
|
||||||
|
@ -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
|
||||||
|
|
||||||
|
|
|
@ -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
|
||||||
|
@ -35,7 +36,6 @@ module Generators
|
||||||
generate_xml
|
generate_xml
|
||||||
end
|
end
|
||||||
|
|
||||||
|
|
||||||
##
|
##
|
||||||
# Generate:
|
# Generate:
|
||||||
#
|
#
|
||||||
|
@ -66,7 +66,7 @@ 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,
|
||||||
|
@ -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
|
||||||
|
|
||||||
|
|
Loading…
Add table
Add a link
Reference in a new issue