iownbey-rdoc 2.0.1

data/lib/rdoc/generator/ri.rb

@@ -0,0 +1,229 @@
+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
+
+  class << self
+    protected :new
+  end
+
+  ##
+  # Set up a new RDoc::Generator::RI.
+
+  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 recure into this classes constituent classess
+    from_class.each_classmodule do |mod|
+      process_class(mod)
+    end
+  end
+
+  def generate_class_info(cls)
+    if cls === RDoc::NormalModule
+      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/lib/rdoc/generator/texinfo.rb

@@ -0,0 +1,84 @@
+require 'rdoc/rdoc'
+require 'rdoc/generator'
+require 'rdoc/markup/to_texinfo'
+
+module RDoc
+  RDoc::GENERATORS['texinfo'] = RDoc::Generator.new("rdoc/generator/texinfo",
+                                                    :Texinfo,
+                                                    'texinfo')
+  module Generator
+    # This generates Texinfo files for viewing with GNU Info or Emacs
+    # from RDoc extracted from Ruby source files.
+    class Texinfo
+      # What should the .info file be named by default?
+      DEFAULT_INFO_FILENAME = 'rdoc.info'
+
+      include Generator::MarkUp
+
+      # Accept some options
+      def initialize(options)
+        @options = options
+        @options.inline_source = true
+        @options.op_name ||= 'rdoc.texinfo'
+        @options.formatter = ::RDoc::Markup::ToTexInfo.new
+      end
+
+      # Generate the +texinfo+ files
+      def generate(toplevels)
+        @toplevels = toplevels
+        @files, @classes = ::RDoc::Generator::Context.build_indicies(@toplevels,
+                                                                     @options)
+
+        (@files + @classes).each { |x| x.value_hash }
+
+        open(@options.op_name, 'w') do |f|
+          f.puts TexinfoTemplate.new('files' => @files,
+                                     'classes' => @classes,
+                                     'filename' => @options.op_name.gsub(/texinfo/, 'info'),
+                                     'title' => @options.title).render
+        end
+        # TODO: create info files and install?
+      end
+
+      class << self
+        # Factory? We don't need no stinkin' factory!
+        alias_method :for, :new
+      end
+    end
+
+    # Basically just a wrapper around ERB.
+    # Should probably use RDoc::TemplatePage instead
+    class TexinfoTemplate
+      BASE_DIR = ::File.expand_path(::File.dirname(__FILE__)) # have to calculate this when the file's loaded.
+
+      def initialize(values, file = 'texinfo.erb')
+        @v, @file = [values, file]
+      end
+     
+      def template
+        ::File.read(::File.join(BASE_DIR, 'texinfo', @file))
+      end
+
+      # Go!
+      def render
+        ERB.new(template).result binding
+      end
+
+      def href(location, text)
+        text # TODO: how does texinfo do hyperlinks?
+      end
+
+      def target(name, text)
+        text # TODO: how do hyperlink targets work?
+      end
+
+      # TODO: this is probably implemented elsewhere?
+      def method_prefix(section)
+        { 'Class' => '.',
+          'Module' => '::',
+          'Instance' => '#',
+        }[section['category']]
+      end
+    end
+  end
+end

data/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 # section["method_list"] %>
+<%   end %>
+<% end # @v['class']["sections"] %>
+<% end %>

data/lib/rdoc/generator/texinfo/file.texinfo.erb

@@ -0,0 +1,6 @@
+<% if false %>
+<h2>File: <%= @v['file']["short_name"] %></h2>
+Path: <%= @v['file']["full_path"] %>
+
+<%= TexinfoTemplate.new(@v, 'content.texinfo.erb').render %>
+<% end %>

data/lib/rdoc/generator/texinfo/method.texinfo.erb

@@ -0,0 +1,6 @@
+@node <%= @v['class']['full_name'].gsub(/::/, '-') %><%= method_prefix @v['list'] %><%= @v['method']['name'] %>
+@section <%= @v['class']["classmod"] %> <%= @v['class']['full_name'] %><%= method_prefix @v['list'] %><%= @v['method']['name'] %>
+<%= @v['method']["type"] %> <%= @v['method']["category"] %> method:
+<%= target @v['method']["aref"], @v['method']['callseq'] ||
+                                 @v['method']["name"] + @v['method']["params"] %>
+<%= @v['method']["m_desc"] %>

data/lib/rdoc/generator/texinfo/texinfo.erb

@@ -0,0 +1,28 @@
+\input texinfo   @c -*-texinfo-*-
+@c %**start of header
+@setfilename <%= @v['filename'] %>
+@settitle <%= @v['title'] %>
+@c %**end of header
+
+@contents @c TODO: whitespace is a mess... =\
+
+@ifnottex
+@node Top
+
+@top <%= @v['title'] %>
+@end ifnottex
+
+<% if @f = @v['files'].detect { |f| f.name =~ /Readme/i }  %>
+<%= @f.values['description'] %><% end %>
+
+@menu
+<% @v['classes'].each do |klass| %>
+* <%= klass.name.gsub(/::/, '-') %>::<% end %>
+@c TODO: add files
+@end menu
+
+<% (@v['classes'] || []).each_with_index do |klass, i| %>
+<%= TexinfoTemplate.new(@v.merge('class' => klass.values), 
+                        'class.texinfo.erb').render %><% end %>
+
+@bye

data/lib/rdoc/generator/xml.rb

@@ -0,0 +1,120 @@
+require 'rdoc/generator/html'
+
+##
+# Generate XML output as one big file
+
+class RDoc::Generator::XML < RDoc::Generator::HTML
+
+  ##
+  # Standard generator factory
+
+  def self.for(options)
+    new(options)
+  end
+
+  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)
+    @info       = info
+    @files      = []
+    @classes    = []
+    @hyperlinks = {}
+
+    build_indices
+    generate_xml
+  end
+
+  ##
+  # Generate:
+  #
+  # * a list of HtmlFile objects for each TopLevel object.
+  # * a list of HtmlClass 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
+    @info.each do |toplevel|
+      @files << RDoc::Generator::HtmlFile.new(toplevel, @options, RDoc::Generator::FILE_DIR)
+    end
+
+    RDoc::TopLevel.all_classes_and_modules.each do |cls|
+      build_class_list(cls, @files[0], RDoc::Generator::CLASS_DIR)
+    end
+  end
+
+  def build_class_list(from, html_file, class_dir)
+    @classes << RDoc::Generator::HtmlClass.new(from, html_file, class_dir, @options)
+    from.each_classmodule do |mod|
+      build_class_list(mod, html_file, class_dir)
+    end
+  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)
+    }
+
+    # this method is defined in the template file
+    write_extra_pages if defined? write_extra_pages
+
+    template = RDoc::TemplatePage.new @template::ONE_PAGE
+
+    if @options.op_name
+      opfile = File.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
+
+  def gen_file_index
+    gen_an_index(@files, 'Files')
+  end
+
+  def gen_class_index
+    gen_an_index(@classes, 'Classes')
+  end
+
+  def gen_method_index
+    gen_an_index(RDoc::Generator::HtmlMethod.all_methods, 'Methods')
+  end
+
+  def gen_an_index(collection, title)
+    res = []
+    collection.sort.each do |f|
+      if f.document_self
+        res << { "href" => f.path, "name" => f.index_name }
+      end
+    end
+
+    return {
+      "entries" => res,
+      'list_title' => title,
+      'index_url'  => main_url,
+    }
+  end
+
+end
+