shoesgem 0.1424.0

data/shoes/ruby/lib/rdoc/generator/html.rb

@@ -0,0 +1,445 @@
+require 'fileutils'
+
+require 'rdoc/generator'
+require 'rdoc/markup/to_html'
+
+##
+# 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 RDoc::Generator::HTML
+
+  include RDoc::Generator::MarkUp
+
+  ##
+  # Generator may need to return specific subclasses depending on the
+  # options they are passed. Because of this we create them using a factory
+
+  def self.for(options)
+    RDoc::Generator::AllReferences.reset
+    RDoc::Generator::Method.reset
+
+    if options.all_one_file
+      RDoc::Generator::HTMLInOne.new options
+    else
+      new options
+    end
+  end
+
+  class << self
+    protected :new
+  end
+
+  ##
+  # Set up a new HTML generator. Basically all we do here is load up the
+  # correct output temlate
+
+  def initialize(options) #:not-new:
+    @options = options
+    load_html_template
+  end
+
+  ##
+  # Build the initial indices and output objects
+  # based on an array of TopLevel objects containing
+  # the extracted information.
+
+  def generate(toplevels)
+    @toplevels  = toplevels
+    @files      = []
+    @classes    = []
+
+    write_style_sheet
+    gen_sub_directories
+    build_indices
+    generate_html
+  end
+
+  private
+
+  ##
+  # Load up the HTML template specified in the options.
+  # If the template name contains a slash, use it literally
+
+  def load_html_template
+    #
+    # If the template is not a path, first look for it
+    # in rdoc's HTML template directory.  Perhaps this behavior should
+    # be reversed (first try to include the template and, only if that
+    # fails, try to include it in the default template directory).
+    # One danger with reversing the behavior, however, is that
+    # if something like require 'html' could load up an
+    # unrelated file in the standard library or in a gem.
+    #
+    template = @options.template
+
+    unless template =~ %r{/|\\} then
+      template = File.join('rdoc', 'generator', @options.generator.key,
+                           template)
+    end
+
+    begin
+      require template
+
+      @template = self.class.const_get @options.template.upcase
+      @options.template_class = @template
+    rescue LoadError => e
+      #
+      # The template did not exist in the default template directory, so
+      # see if require can find the template elsewhere (in a gem, for
+      # instance).
+      #
+      if(e.message[template] && template != @options.template)
+        template = @options.template
+        retry
+      end
+
+      $stderr.puts "Could not find HTML template '#{template}': #{e.message}"
+      exit 99
+    end
+  end
+
+  ##
+  # Write out the style sheet used by the main frames
+
+  def write_style_sheet
+    return unless @template.constants.include? :STYLE or
+                  @template.constants.include? 'STYLE'
+
+    template = RDoc::TemplatePage.new @template::STYLE
+
+    unless @options.css then
+      open RDoc::Generator::CSS_NAME, 'w' do |f|
+        values = {}
+
+        if @template.constants.include? :FONTS or
+           @template.constants.include? 'FONTS' then
+          values["fonts"] = @template::FONTS
+        end
+
+        template.write_html_on(f, values)
+      end
+    end
+  end
+
+  ##
+  # See the comments at the top for a description of the directory structure
+
+  def gen_sub_directories
+    FileUtils.mkdir_p RDoc::Generator::FILE_DIR
+    FileUtils.mkdir_p RDoc::Generator::CLASS_DIR
+  rescue
+    $stderr.puts $!.message
+    exit 1
+  end
+
+  def build_indices
+    @files, @classes = RDoc::Generator::Context.build_indices(@toplevels,
+                                                              @options)
+  end
+
+  ##
+  # Generate all the HTML
+
+  def generate_html
+    @main_url = main_url
+
+    # the individual descriptions for files and classes
+    gen_into(@files)
+    gen_into(@classes)
+
+    # and the index files
+    gen_file_index
+    gen_class_index
+    gen_method_index
+    gen_main_index
+
+    # this method is defined in the template file
+    values = {
+      'title_suffix' => CGI.escapeHTML("[#{@options.title}]"),
+      'charset'      => @options.charset,
+      'style_url'    => style_url('', @options.css),
+    }
+
+    @template.write_extra_pages(values) if @template.respond_to?(:write_extra_pages)
+  end
+
+  def gen_into(list)
+    #
+    # The file, class, and method lists technically should be regenerated
+    # for every output file, in order that the relative links be correct
+    # (we are worried here about frameless templates, which need this
+    # information for every generated page).  Doing this is a bit slow,
+    # however.  For a medium-sized gem, this increased rdoc's runtime by
+    # about 5% (using the 'time' command-line utility).  While this is not
+    # necessarily a problem, I do not want to pessimize rdoc for large
+    # projects, however, and so we only regenerate the lists when the
+    # directory of the output file changes, which seems like a reasonable
+    # optimization.
+    #
+    file_list = {}
+    class_list = {}
+    method_list = {}
+    prev_op_dir = nil
+
+    list.each do |item|
+      next unless item.document_self
+
+      op_file = item.path
+      op_dir = File.dirname(op_file)
+
+      if(op_dir != prev_op_dir)
+        file_list = index_to_links op_file, @files
+        class_list = index_to_links op_file, @classes
+        method_list = index_to_links op_file, RDoc::Generator::Method.all_methods
+      end
+      prev_op_dir = op_dir
+
+      FileUtils.mkdir_p op_dir
+
+      open op_file, 'w' do |io|
+        item.write_on io, file_list, class_list, method_list
+      end
+    end
+  end
+
+  def gen_file_index
+    gen_an_index @files, 'Files', @template::FILE_INDEX, "fr_file_index.html"
+  end
+
+  def gen_class_index
+    gen_an_index(@classes, 'Classes', @template::CLASS_INDEX,
+                 "fr_class_index.html")
+  end
+
+  def gen_method_index
+    gen_an_index(RDoc::Generator::Method.all_methods, 'Methods',
+                 @template::METHOD_INDEX, "fr_method_index.html")
+  end
+
+  def gen_an_index(collection, title, template, filename)
+    template = RDoc::TemplatePage.new @template::FR_INDEX_BODY, template
+    res = []
+    collection.sort.each do |f|
+      if f.document_self
+        res << { "href" => f.path, "name" => f.index_name }
+      end
+    end
+
+    values = {
+      "entries"    => res,
+      'title'      => CGI.escapeHTML("#{title} [#{@options.title}]"),
+      'list_title' => CGI.escapeHTML(title),
+      'index_url'  => @main_url,
+      'charset'    => @options.charset,
+      'style_url'  => style_url('', @options.css),
+    }
+
+    open filename, 'w' do |f|
+      template.write_html_on(f, values)
+    end
+  end
+
+  ##
+  # The main index page is mostly a template frameset, but includes the
+  # initial page. If the <tt>--main</tt> option was given, we use this as
+  # our main page, otherwise we use the first file specified on the command
+  # line.
+
+  def gen_main_index
+    if @template.const_defined? :FRAMELESS then
+      #
+      # If we're using a template without frames, then just redirect
+      # to it from index.html.
+      #
+      # One alternative to this, expanding the main page's template into
+      # index.html, is tricky because the relative URLs will be different
+      # (since index.html is located in at the site's root,
+      # rather than within a files or a classes subdirectory).
+      #
+      open 'index.html', 'w'  do |f|
+        f.puts(%{<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+               "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">})
+        f.puts(%{<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en"
+                lang="en">})
+        f.puts(%{<head>})
+        f.puts(%{<title>#{CGI.escapeHTML(@options.title)}</title>})
+        f.puts(%{<meta http-equiv="refresh" content="0; url=#{@main_url}" />})
+        f.puts(%{</head>})
+        f.puts(%{<body></body>})
+        f.puts(%{</html>})
+      end
+    else
+      main = RDoc::TemplatePage.new @template::INDEX
+
+      open 'index.html', 'w'  do |f|
+        style_url = style_url '', @options.css
+        
+        classes = @classes.sort.map { |klass| klass.value_hash }
+        
+        values = {
+          'initial_page'  => @main_url,
+          'style_url'     => style_url('', @options.css),
+          'title'         => CGI.escapeHTML(@options.title),
+          'charset'       => @options.charset,
+          'classes'       => classes,
+        }
+        
+        values['inline_source'] = @options.inline_source
+
+        main.write_html_on f, values
+      end
+    end
+  end
+
+  def index_to_links(output_path, collection)
+    collection.sort.map do |f|
+      next unless f.document_self
+      { "href" => RDoc::Markup::ToHtml.gen_relative_url(output_path, f.path),
+        "name" => f.index_name }
+    end.compact
+  end
+
+  ##
+  # Returns the url of the main page
+
+  def main_url
+    main_page = @options.main_page
+
+    #
+    # If a main page has been specified (--main), then search for it
+    # in the AllReferences array.  This allows either files or classes
+    # to be used for the main page.
+    #
+    if main_page then
+      main_page_ref = RDoc::Generator::AllReferences[main_page]
+
+      if main_page_ref then
+        return main_page_ref.path
+      else
+        $stderr.puts "Could not find main page #{main_page}"
+      end
+    end
+
+    #
+    # No main page has been specified, so just use the README.
+    #
+    @files.each do |file|
+      if file.name =~ /^README/ then
+        return file.path
+      end
+    end
+
+    #
+    # There's no README (shame! shame!).  Just use the first file
+    # that will be documented.
+    #
+    @files.each do |file|
+      if file.document_self then
+        return file.path
+      end
+    end
+
+    #
+    # There are no files to be documented...  Something seems very wrong.
+    #
+    raise RDoc::Error, "Couldn't find anything to document (perhaps :stopdoc: has been used in all classes)!"
+  end
+  private :main_url
+
+end
+
+class RDoc::Generator::HTMLInOne < RDoc::Generator::HTML
+
+  def initialize(*args)
+    super
+  end
+
+  ##
+  # Build the initial indices and output objects
+  # based on an array of TopLevel objects containing
+  # the extracted information.
+
+  def generate(info)
+    @toplevels  = info
+    @hyperlinks = {}
+
+    build_indices
+    generate_xml
+  end
+
+  ##
+  # Generate:
+  #
+  # * a list of RDoc::Generator::File objects for each TopLevel object.
+  # * a list of RDoc::Generator::Class objects for each first level
+  #   class or module in the TopLevel objects
+  # * a complete list of all hyperlinkable terms (file,
+  #   class, module, and method names)
+
+  def build_indices
+    @files, @classes = RDoc::Generator::Context.build_indices(@toplevels,
+                                                              @options)
+  end
+
+  ##
+  # Generate all the HTML. For the one-file case, we generate
+  # all the information in to one big hash
+
+  def generate_xml
+    values = {
+      'charset' => @options.charset,
+      'files'   => gen_into(@files),
+      'classes' => gen_into(@classes),
+      'title'   => CGI.escapeHTML(@options.title),
+    }
+
+    template = RDoc::TemplatePage.new @template::ONE_PAGE
+
+    if @options.op_name
+      opfile = open @options.op_name, 'w'
+    else
+      opfile = $stdout
+    end
+    template.write_html_on(opfile, values)
+  end
+
+  def gen_into(list)
+    res = []
+    list.each do |item|
+      res << item.value_hash
+    end
+    res
+  end
+end

data/shoes/ruby/lib/rdoc/generator/ri.rb

@@ -0,0 +1,226 @@
+require 'rdoc/generator'
+require 'rdoc/markup/to_flow'
+
+require 'rdoc/ri/cache'
+require 'rdoc/ri/reader'
+require 'rdoc/ri/writer'
+require 'rdoc/ri/descriptions'
+
+class RDoc::Generator::RI
+
+  ##
+  # Generator may need to return specific subclasses depending on the
+  # options they are passed. Because of this we create them using a factory
+
+  def self.for(options)
+    new(options)
+  end
+
+  ##
+  # Set up a new ri generator
+
+  def initialize(options) #:not-new:
+    @options   = options
+    @ri_writer = RDoc::RI::Writer.new "."
+    @markup    = RDoc::Markup.new
+    @to_flow   = RDoc::Markup::ToFlow.new
+
+    @generated = {}
+  end
+
+  ##
+  # Build the initial indices and output objects based on an array of
+  # TopLevel objects containing the extracted information.
+
+  def generate(toplevels)
+    RDoc::TopLevel.all_classes_and_modules.each do |cls|
+      process_class cls
+    end
+  end
+
+  def process_class(from_class)
+    generate_class_info(from_class)
+
+    # now recurse into this class' constituent classes
+    from_class.each_classmodule do |mod|
+      process_class(mod)
+    end
+  end
+
+  def generate_class_info(cls)
+    case cls
+    when RDoc::NormalModule then
+      cls_desc = RDoc::RI::ModuleDescription.new
+    else
+      cls_desc = RDoc::RI::ClassDescription.new
+      cls_desc.superclass = cls.superclass
+    end
+
+    cls_desc.name        = cls.name
+    cls_desc.full_name   = cls.full_name
+    cls_desc.comment     = markup(cls.comment)
+
+    cls_desc.attributes = cls.attributes.sort.map do |a|
+      RDoc::RI::Attribute.new(a.name, a.rw, markup(a.comment))
+    end
+
+    cls_desc.constants = cls.constants.map do |c|
+      RDoc::RI::Constant.new(c.name, c.value, markup(c.comment))
+    end
+
+    cls_desc.includes = cls.includes.map do |i|
+      RDoc::RI::IncludedModule.new(i.name)
+    end
+
+    class_methods, instance_methods = method_list(cls)
+
+    cls_desc.class_methods = class_methods.map do |m|
+      RDoc::RI::MethodSummary.new(m.name)
+    end
+
+    cls_desc.instance_methods = instance_methods.map do |m|
+      RDoc::RI::MethodSummary.new(m.name)
+    end
+
+    update_or_replace(cls_desc)
+
+    class_methods.each do |m|
+      generate_method_info(cls_desc, m)
+    end
+
+    instance_methods.each do |m|
+      generate_method_info(cls_desc, m)
+    end
+  end
+
+  def generate_method_info(cls_desc, method)
+    meth_desc = RDoc::RI::MethodDescription.new
+    meth_desc.name = method.name
+    meth_desc.full_name = cls_desc.full_name
+    if method.singleton
+      meth_desc.full_name += "::"
+    else
+      meth_desc.full_name += "#"
+    end
+    meth_desc.full_name << method.name
+
+    meth_desc.comment = markup(method.comment)
+    meth_desc.params = params_of(method)
+    meth_desc.visibility = method.visibility.to_s
+    meth_desc.is_singleton = method.singleton
+    meth_desc.block_params = method.block_params
+
+    meth_desc.aliases = method.aliases.map do |a|
+      RDoc::RI::AliasName.new(a.name)
+    end
+
+    @ri_writer.add_method(cls_desc, meth_desc)
+  end
+
+  private
+
+  ##
+  # Returns a list of class and instance methods that we'll be documenting
+
+  def method_list(cls)
+    list = cls.method_list
+    unless @options.show_all
+      list = list.find_all do |m|
+        m.visibility == :public || m.visibility == :protected || m.force_documentation
+      end
+    end
+
+    c = []
+    i = []
+    list.sort.each do |m|
+      if m.singleton
+        c << m
+      else
+        i << m
+      end
+    end
+    return c,i
+  end
+
+  def params_of(method)
+    if method.call_seq
+      method.call_seq
+    else
+      params = method.params || ""
+
+      p = params.gsub(/\s*\#.*/, '')
+      p = p.tr("\n", " ").squeeze(" ")
+      p = "(" + p + ")" unless p[0] == ?(
+
+      if (block = method.block_params)
+        block.gsub!(/\s*\#.*/, '')
+        block = block.tr("\n", " ").squeeze(" ")
+        if block[0] == ?(
+          block.sub!(/^\(/, '').sub!(/\)/, '')
+        end
+        p << " {|#{block.strip}| ...}"
+      end
+      p
+    end
+  end
+
+  def markup(comment)
+    return nil if !comment || comment.empty?
+
+    # Convert leading comment markers to spaces, but only
+    # if all non-blank lines have them
+
+    if comment =~ /^(?>\s*)[^\#]/
+      content = comment
+    else
+      content = comment.gsub(/^\s*(#+)/)  { $1.tr('#',' ') }
+    end
+    @markup.convert(content, @to_flow)
+  end
+
+  ##
+  # By default we replace existing classes with the same name. If the
+  # --merge option was given, we instead merge this definition into an
+  # existing class. We add our methods, aliases, etc to that class, but do
+  # not change the class's description.
+
+  def update_or_replace(cls_desc)
+    old_cls = nil
+
+    if @options.merge
+      rdr = RDoc::RI::Reader.new RDoc::RI::Cache.new(@options.op_dir)
+
+      namespace = rdr.top_level_namespace
+      namespace = rdr.lookup_namespace_in(cls_desc.name, namespace)
+      if namespace.empty?
+        $stderr.puts "You asked me to merge this source into existing "
+        $stderr.puts "documentation. This file references a class or "
+        $stderr.puts "module called #{cls_desc.name} which I don't"
+        $stderr.puts "have existing documentation for."
+        $stderr.puts
+        $stderr.puts "Perhaps you need to generate its documentation first"
+        exit 1
+      else
+        old_cls = namespace[0]
+      end
+    end
+
+    prev_cls = @generated[cls_desc.full_name]
+
+    if old_cls and not prev_cls then
+      old_desc = rdr.get_class old_cls
+      cls_desc.merge_in old_desc
+    end
+
+    if prev_cls then
+      cls_desc.merge_in prev_cls
+    end
+
+    @generated[cls_desc.full_name] = cls_desc
+
+    @ri_writer.remove_class cls_desc
+    @ri_writer.add_class cls_desc
+  end
+
+end
+

data/shoes/ruby/lib/rdoc/generator/texinfo/class.texinfo.erb

@@ -0,0 +1,44 @@
+@node <%= @v['class']['full_name'].gsub(/::/, '-') %>
+@chapter <%= @v['class']["classmod"] %> <%= @v['class']['full_name'] %>
+
+<% if @v['class']["parent"] and @v['class']['par_url'] %>
+Inherits <%= href @v['class']["par_url"], @v['class']["parent"] %><% end %>
+
+<%= @v['class']["description"] %>
+
+<% if @v['class']["includes"] %>
+Includes
+<%   @v['class']["includes"].each do |include| %>
+* <%=  href include["aref"], include["name"] %>
+<%   end # @v['class']["includes"] %>
+<% end %>
+
+<% if @v['class']["sections"] %>
+<%   @v['class']["sections"].each do |section| %>
+<%     if section["attributes"] %>
+Attributes
+<%       section["attributes"].each do |attributes| %>
+* <%=      attributes["name"] %> <%= attributes["rw"] %> <%= attributes["a_desc"] %>
+<%       end # section["attributes"] %>
+<%     end %>
+<%   end %>
+
+<%   @v['class']["sections"].each do |section| %>
+<%     if section["method_list"] %>
+Methods
+@menu
+<%     section["method_list"].each_with_index do |method_list, i| %>
+<%= i %>
+<%       (method_list["methods"] || []).each do |method| %>
+* <%= @v['class']['full_name'].gsub(/::/, '-') %><%= method_prefix method_list %><%= method['name'] %>::<% end %>
+<% end %>
+@end menu
+
+<%     section["method_list"].each do |method_list| %>
+<%       (method_list["methods"] || []).uniq.each do |method| %>
+<%=        TexinfoTemplate.new(@v.merge({'method' => method, 'list' => method_list}),
+                               'method.texinfo.erb').render %><% end %>
+<%       end %>
+<%     end # if section["method_list"] %>
+<% end # @v['class']["sections"] %>
+<% end %>