rdoc-babel 0.9.1

data/.autotest

@@ -0,0 +1,12 @@
+require 'autotest/restart'
+
+Autotest.add_hook :initialize do |at|
+  at.testlib = 'minitest/unit'
+  class << at
+    alias zen_path_to_classname path_to_classname
+    def path_to_classname(s)
+      zen_path_to_classname(s).sub('Rdoc', 'RDoc')
+    end
+  end
+end
+

data/HISTORY.rdoc

@@ -0,0 +1,8 @@
+
+=== 0.9.0 / 2010-10-02
+
+Initial version, developed along with {RDoc}[http://github.com/rdoc/rdoc] 3.0.
+
+=== 0.9.1 / 2011-07-16
+
+First public release.

data/Manifest.txt

@@ -0,0 +1,28 @@
+.autotest
+HISTORY.rdoc
+Manifest.txt
+Rakefile
+README.rdoc
+lib/rdoc/discover.rb
+lib/rdoc/generator/babel.rb
+lib/rdoc/generator/ruby-lang/class-page.html.erb
+lib/rdoc/generator/ruby-lang/file-page.html.erb
+lib/rdoc/generator/ruby-lang/images/zoom.png
+lib/rdoc/generator/ruby-lang/index.html.erb
+lib/rdoc/generator/ruby-lang/indexes.html.erb
+lib/rdoc/generator/ruby-lang/rdoc.css
+lib/rdoc/generator/ruby-lang/scripts/indexFrame.js
+lib/rdoc/generator/ruby-lang/scripts/jquery.js
+lib/rdoc/generator/ruby-lang/scripts/jquery.quicksearch.js
+lib/rdoc/generator/ruby-lang/scripts/mainFrame.js
+lib/rdoc_babel.rb
+test/data/ancestors.rb
+test/data/commented.rb
+test/data/context_alias.rb
+test/data/HISTORY.rdoc
+test/data/main_file.rb
+test/data/not_commented.rb
+test/data/no_class_nor_module.rb
+test/data/no_content.rb
+test/data/README.rdoc
+test/test_rdoc_generator_babel.rb

data/README.rdoc

@@ -0,0 +1,103 @@
+= Babel
+
+* http://github.com/thyresias/rdoc-babel
+
+== Description
+
+Babel is an RDoc formatter producing HTML documentation.
+The default template is +ruby-lang+.
+
+You are welcome to propose changes or enhancements,
+and to contribute alternate templates or style sheets.
+
+=== Features of the "ruby-lang" template
+
+- Look and feel inspired from ruby-lang.org[http://www.ruby-lang.org/].
+- Dual-frame output, with indexes on the left.
+- Search boxes for classes and methods.
+- Links to undocumented classes/methods are grayed.
+- Highlights target methods, attributes and constants.
+- Adds links to ancestor methods/attributes.
+- Borrows some ideas (and one icon) from Darkfish.
+- Tested on Firefox 3.5 & 5, Chrome 9 & 12, Safari 4 & 5.
+
+== Synopsis
+
+To output documentation formatted by Babel, use the <tt>--format/-f</tt>
+RDoc switch. For instance, to generate the documentation for Ruby core:
+
+  $ gem install rdoc-babel
+  $ cd ~/.rvm/src/ruby-1.8.7-p302
+  $ rdoc -f babel -a -t "Ruby 1.8.7 Core" -o ~/docs/ruby_core_187 *.c
+
+Using rake:
+
+  require 'rdoc/task'
+
+  RDoc::Task.new do |t|
+    Dir.chdir '~/.rvm/src/ruby-1.9.2-p0'
+    rdoc.options <<
+      '--format' << 'babel' <<
+      '--all'
+    t.title = "Ruby 1.9.2 Core"
+    t.rdoc_dir = '~/docs/ruby_core_192'
+    t.rdoc_files.concat Dir['*.c']
+  end
+
+To make Babel the default format when generating RDoc documentation,
+define the RDOCOPT environment variable in the appropriate file
+(e.g., <tt>~/.bashrc</tt>):
+
+  export RDOCOPT="--format babel"
+
+== Specific options
+
+Babel supports specific options in addition to the standard RDoc options:
+
+[<tt>--style</tt> _url_, +-s+]
+
+  Specifies the URL of a stylesheet that the template should use.
+  The default is "rdoc.css".
+
+[<tt>--see-standard-ancestors</tt>]
+
+  Add links to Kernel/Object ancestor methods.
+
+  When a method or attribute is defined in a class/module, and is also
+  present in an ancestor, Babel adds a link to the ancestor method/attribute
+  in the description ("See also ..."). Unless this option is specified,
+  this annotation is not generated for Object and Kernel ancestor methods.
+
+== Requirements
+
+- Ruby >= 1.8.7
+- RDoc >= 3.0
+
+== Installation
+
+  [sudo] gem install rdoc-babel
+
+== License
+
+(The MIT License)
+
+Copyright (c) 2010 Thierry Lambert
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Rakefile

@@ -0,0 +1,38 @@
+require 'rubygems'
+require 'hoe'
+
+Hoe.spec 'rdoc-babel' do
+
+  developer('Thierry Lambert', 'thyresias@gmail.com')
+
+  self.summary = "An RDoc formatter producing HTML documentation."
+  self.description = paragraphs_of('README.rdoc', 3, 6).join("\n\n")
+
+  self.readme_file = 'README.rdoc'
+  self.history_file = 'HISTORY.rdoc'
+  self.extra_rdoc_files = ['README.rdoc', 'HISTORY.rdoc']
+
+  self.remote_rdoc_dir = ''
+  self.testlib = :minitest
+
+  self.extra_deps << ['rdoc', '~> 3.0']
+
+  self.extra_dev_deps << ['minitest', '>= 1.7']
+  self.extra_dev_deps << ['nokogiri', '~> 1.4']
+
+  spec_extras[:homepage] = 'http://github.com/thyresias/babel'
+  spec_extras[:rdoc_options] = [
+    '--main', 'README.rdoc',
+  ]
+
+  #spec_extras[:post_install_message] = <<-EOS
+  #  the crash for creating Babel documentation is due to a RubyGem bug
+  #EOS
+
+end
+
+task :file_list do
+  puts Dir['*'].reject { |f| File.directory? f }
+  puts Dir['lib/**/*'].reject { |f| File.directory? f }
+  puts Dir['test/**/*'].reject { |f| File.directory? f }
+end

data/lib/rdoc/discover.rb

@@ -0,0 +1 @@
+require 'rdoc/generator/babel'

data/lib/rdoc/generator/babel.rb

@@ -0,0 +1,407 @@
+require 'rdoc'
+require 'rdoc/rdoc'
+#require 'rdoc/generator'
+require 'pathname'
+require 'fileutils'
+require 'erb'
+
+require 'rdoc/generator/markup'
+
+##
+# Babel RDoc HTML Generator.
+# (Initially a variation of Darkfish.)
+
+class RDoc::Generator::Babel
+
+  RDoc::RDoc.add_generator(self)
+
+  include ERB::Util
+
+  # Directory containing babel templates.
+  # Each template is in a subdirectory named after the template.
+
+  TEMPLATE_ROOT = Pathname.new(__FILE__).expand_path.dirname
+
+  ##
+  # Babel-specific options.
+
+  module Options
+
+    ##
+    # A hash <tt>option => value</tt>.
+
+    attr_accessor :babel_options
+
+  end
+
+  class << self
+
+    # Standard generator factory method.
+
+    alias for new
+
+    # Add Babel options to RDoc standard options.
+
+    def setup_options(rdoc_options)
+
+      options = {
+        :stylesheet_url => nil,
+        #:index_attributes => false,
+        #:ancestor_lists => false,
+        #:list_standard_ancestors => false,
+        :see_standard_ancestors => false,
+      }
+
+      rdoc_options.extend Options
+      rdoc_options.babel_options = options
+
+      opt = rdoc_options.option_parser
+
+      opt.separator "Babel options:"
+      opt.separator nil
+
+      opt.on('--style=URL', '-s',
+          'Specifies the URL of a stylesheet',
+          'that the template should use.',
+          'The default is "rdoc.css".') do |value|
+        options[:stylesheet_url] = value
+      end
+      opt.separator nil
+
+=begin
+      opt.on('--index-attributes',
+          'Include attributes in the method index.',
+          'By default, only methods are included.') do |value|
+        options[:index_attributes] = true
+      end
+      opt.separator nil
+
+      opt.on('--ancestor-lists',
+          'Add lists of ancestor methods, attributes,',
+          'aliases and constants in the documentation',
+          'of a class/module.') do |value|
+        options[:ancestor_lists] = true
+      end
+      opt.separator nil
+
+      opt.on('--list-standard-ancestors',
+          'Include Kernel/Object methods',
+          'in ancestor methods.') do |value|
+        options[:list_standard_ancestors] = true
+      end
+      opt.separator nil
+=end
+
+      opt.on('--see-standard-ancestors',
+          'Add links to Kernel/Object',
+          'ancestor methods.') do |value|
+        options[:see_standard_ancestors] = true
+      end
+      opt.separator nil
+
+    end
+
+  end
+
+  # Saves the options, makes sure the template is found.
+
+  def initialize(options)
+    @options = options
+    @babel_options = options.babel_options
+    @see_standard_ancestors = @babel_options[:see_standard_ancestors]
+    RDoc::AnyMethod.add_line_numbers = options.line_numbers
+    @options.template = 'ruby-lang' if @options.template == 'babel' # TODO leave template nil
+    @template_dir = TEMPLATE_ROOT + @options.template
+    @template_dir.directory? or raise RDoc::Error, "template not found: '#@template_dir'"
+    @source_dir = Pathname.pwd.expand_path
+  end
+
+  # Directory for generated class/module files.
+  # Used by RDoc::ClassModule to build paths.
+
+  def class_dir
+    'classes'
+  end
+
+  # Directory for generated TopLevel files.
+  # Used by RDoc::TopLevel to build paths.
+
+  def file_dir
+    'files'
+  end
+
+  # Generates the documentation.
+
+  def generate(top_levels)
+
+    # set instance variables
+
+    @output_dir = Pathname.new(@options.op_dir).expand_path(@source_dir)
+    @all_classes_and_modules = RDoc::TopLevel.all_classes_and_modules.sort
+    @unique_classes_and_modules = RDoc::TopLevel.unique_classes_and_modules.sort
+
+    @all_methods = @unique_classes_and_modules.
+      inject([]) { |a,m| a.concat m.method_list }.
+      sort { |a,b| [a, a.parent_name] <=> [b, b.parent_name] }
+
+    @all_files = top_levels # not sorted: keep command line order
+    @files_with_comment = @all_files.reject { |f| f.comment.empty? }
+    @simple_files = @files_with_comment.select { |f| f.parser == RDoc::Parser::Simple }
+
+    @files_to_display =
+      if @unique_classes_and_modules.empty?
+        @all_files
+      else
+        @simple_files
+      end
+
+    @main_file = @options.main_page && @all_files.find { |f| f.full_name == @options.main_page }
+    if @main_file
+      unless @files_to_display.find { |f| f.full_name == @options.main_page }
+        @files_to_display.unshift @main_file
+      end
+    end
+
+    # write the output
+
+    write_static_files
+    generate_indexes
+    generate_class_and_module_files
+    generate_file_files
+
+  rescue StandardError => err
+    debug_msg "%s: %s\n  %s" % [ err.class.name, err.message, err.backtrace.join("\n  ") ]
+    raise
+  end
+
+  # Copy static files to the output directory.
+  # Static files are all files in the template directory
+  # that do not have the <tt>.erb</tt> extension.
+
+  def write_static_files
+    debug_msg "Copying static files"
+    options = { :verbose => $DEBUG_RDOC, :noop => @options.dry_run }
+    static_files = Pathname.
+      glob(@template_dir.to_s + '/**/*').
+      reject { |f| f.extname == '.erb' }
+    static_files.sort.each do |source_path|
+      out_path = @output_dir + source_path.relative_path_from(@template_dir)
+      if source_path.directory?
+        out_path.mkpath unless @options.dry_run
+      else
+        FileUtils.cp source_path.to_s, out_path.dirname.to_s, options
+      end
+    end
+  end
+
+  # Generates +index.html+ and +indexes.html+.
+
+  def generate_indexes
+    @first_page = first_page
+    generate_index('index')
+    generate_index('indexes')
+  end
+
+  # Generates an index page.
+
+  def generate_index(basename)
+    debug_msg "Generating index #{basename}.html"
+    template_file = @template_dir + "#{basename}.html.erb"
+    outfile = @output_dir + "#{basename}.html"
+    render_template(template_file, binding(), outfile)
+  end
+
+  # Generates a documentation page for each class.
+
+  def generate_class_and_module_files
+    template_file = @template_dir + 'class-page.html.erb'
+    debug_msg "Generating class documentation"
+    @unique_classes_and_modules.each do |klass|
+      debug_msg "  %s %s" % [klass.type, klass.full_name]
+      outfile = @output_dir + klass.path
+      @class = klass
+      self.render_template(template_file, binding(), outfile)
+    end
+  end
+
+  # Generates a documentation page for each file.
+
+  def generate_file_files
+    template_file = @template_dir + 'file-page.html.erb'
+    debug_msg "Generating file documentation"
+    @all_files.each do |file|
+      debug_msg "  file #{file.path}"
+      outfile = @output_dir + file.path
+      @file = file
+      self.render_template(template_file, binding(), outfile)
+    end
+  end
+
+  # Returns the first +Context+ object to display in the main frame.
+  # This is, in order:
+  # - The file designated by the +main_page+ option,
+  #   if there is a +TopLevel+ with that name.
+  # - The first simple file that contains a comment
+  #   (in the order given on the command line).
+  # - The first class or module that contains a comment.
+  # - The first file that contains a comment
+  #   (in the order given on the command line).
+  # - The first class or module that has any kind of content.
+  # - The first class or module.
+  # - The first file.
+
+  def first_page
+    # TODO are there cases where main_page = 'README' for 'lib/README'?
+    if @options.main_page && (main_file = @all_files.find { |f| f.full_name == @options.main_page })
+      main_file
+    elsif (file = @simple_files.first)
+      file
+    elsif (cm = @unique_classes_and_modules.find { |k| !k.comment.empty? })
+      cm
+    elsif (file = @files_with_comment.first)
+      file
+    elsif !@unique_classes_and_modules.empty?
+      @unique_classes_and_modules.find { |k| k.any_content } or
+        @unique_classes_and_modules.first
+    else
+      @all_files.first
+    end
+  end
+
+  # Returns the HTML for the description of a method,
+  # with alias information and link to ancestor method/attribute.
+
+  def description(method)
+    desc = method.documented? ? method.description.strip : ''
+    if method.is_alias_for
+      text = method.is_alias_for.documented? ? '<p>' : '<p class="nodoc">'
+      text << 'Alias for ' << link(method, method.is_alias_for) << '</p>'
+      append_with_nl desc, text
+    end
+    if method.see &&
+        (@see_standard_ancestors ||
+         method.see.parent.full_name !~ /^(Object|Kernel)$/)
+      text = method.see.documented? ? '<p>' : '<p class="nodoc">'
+      text << (desc.empty? ? 'See ' : 'See also ')
+      text << link(method, method.see) << '</p>'
+      append_with_nl desc, text
+    end
+    desc = '<p class="nodoc">(not documented)</p>' if desc.empty?
+    unless method.aliases.empty?
+      text = '<p>Also aliased as '
+      text << method.aliases.map { |a| link(method, a) }.join(', ') << '</p>'
+      append_with_nl desc, text
+    end
+    desc
+  end
+
+  # Decorates a call-seq to highlight the method name.
+  # The output will have the method name inside HTML
+  # +span+ tags with CSS class +method_name_class+.
+
+  def decorated_call_seq(method, method_name_class)
+
+    # I assume it is safe to use \001 \002 \003 \004 to escape & < > "
+    text = method.call_seq.strip.gsub(/->/, "\001rarr;")
+    ospan = "\002span class=\004#{method_name_class}\004\003"
+    cspan = "\002/span\003"
+
+    if method.name =~ /^[a-z]/i
+      # look for things like 'IO.open' or 'open' at the beginning of lines
+      name = Regexp.escape(method.name.sub(/=$/, ''))
+      re = Regexp.new('^(\s*)([:\w]+\.)?(' << name << ')', Regexp::MULTILINE)
+      text.gsub!(re, "\\1\\2#{ospan}\\3#{cspan}")
+    elsif method.name =~ /\[\]=?/
+      # [] and []=
+      text.gsub!(/\[/m, "#{ospan}[#{cspan}")
+      text.gsub!(/\]/m, "#{ospan}]#{cspan}")
+    else
+      # operators:
+      # **
+      # -(unary) +(unary) ~
+      # *  /  %
+      # +  -
+      # <<  >>
+      # &
+      # |  ^
+      # >  >=  <  <=
+      # <=> == === =~
+      name = Regexp.escape(method.name)
+      re = Regexp.new(name, Regexp::MULTILINE)
+      text.gsub!(re, "#{ospan}\\&#{cspan}")
+    end
+
+    h(text).gsub("\001", '&').gsub("\002",'<').gsub("\003",'>').gsub("\004",'"').gsub("\n", '<br/>')
+  end
+
+protected
+
+  # Renders the erb template in +template_file+ within the
+  # specified +binding+ context and writes the result to +outfile+.
+
+  def render_template(template_file, binding, outfile)
+
+    debug_msg "  rendering #{outfile}"
+
+    @rel_prefix = @output_dir.relative_path_from(outfile.dirname)
+    @stylesheet_url = @babel_options[:stylesheet_url] || (@rel_prefix + 'rdoc.css').to_s
+
+    template_src = template_file.read
+    template = ERB.new(template_src, nil, '><')
+    template.filename = template_file.to_s
+
+    output = nil
+    begin
+      output = template.result(binding)
+    rescue => e
+      raise RDoc::Error, "Error while evaluating %s: %s (%s at %p)" % [
+          template_file.to_s,
+          e.message, e.class.name,
+          eval("_erbout[-50,50]", binding)
+        ], e.backtrace
+    end
+
+    return if @options.dry_run
+
+    outfile.dirname.mkpath
+    outfile.open('w', 0644) do |ofh|
+      ofh.print(output)
+    end
+
+  end
+
+  # Returns the <a> tag code linking to method +to+ from the page
+  # describing method +from+.
+
+  def link(from, to)
+    href = from.parent.aref_to(to.path)
+    to_parent = to.parent.full_name.dup
+    if @options.show_hash
+      text = from.parent.full_name == to_parent ? '' : to_parent
+      text << (to.singleton ? '::' : '#') << to.name
+    elsif from.parent.full_name == to_parent
+      text = to.name.dup
+    else
+      text = to_parent
+      text << (to.singleton ? '::' : '#') << to.name
+    end
+    %Q(<a href="#{href}">#{h(text)}</a>)
+  end
+
+  # Output progress information if debugging is enabled.
+
+  def debug_msg(msg)
+    $stderr.puts(msg) if $DEBUG_RDOC
+  end
+
+  # Appends string +add+ to +base+ with a newline between the two if needed,
+  # and a final trailing newline.
+
+  def append_with_nl(base, add)
+    base.strip!
+    base.sub!(/\S\z/, "\\&\n")
+    base << add
+    base << "\n"
+  end
+
+end