rdoc-babel 0.9.1

data/lib/rdoc/generator/ruby-lang/scripts/mainFrame.js

@@ -0,0 +1,107 @@
+/*
+ * Script for the main frame.
+ * An adaptation of (darkfish.js by Michael Granger)
+ */
+
+function setupShowSource() {
+  //$('.method-detail').click(showSource);
+  $('.method-heading').click(toggleSource);
+};
+
+function toggleSource(e) {
+  //TODO not when clicking a link
+  $(e.target).parents('.method-detail').find('.method-source-code').slideToggle();
+};
+
+function setupShowConstantValue() {
+  $('#constant-list .const-display').click(toggleValue);
+};
+
+function toggleValue(e) {
+  //TODO not when clicking a link
+  $(this).next().toggle();
+};
+
+function setupShowAllFiles() {
+  var allFiles = $('#all-files');
+  if (allFiles.length == 0) return;
+  var skipBodyClick = false;
+  $('#show-all-files').click(function(e) {
+    e.preventDefault();
+    skipBodyClick = true;
+    if (allFiles.css('display') == 'block')
+      allFiles.css('display', 'none');
+    else
+      allFiles.css('display', 'block');
+  });
+  $('body').click(function() {
+    if (skipBodyClick)
+      skipBodyClick = false;
+    else if (allFiles.css('display') == 'block')
+      allFiles.css('display', 'none');
+  });
+}
+
+function setupResizing() {
+
+  var doc = $('#documentation');
+  var delta = $('body').outerHeight() - doc.height();
+
+  // callback on resize event
+  $(window).resize(function() {
+    frameResized(doc, delta);
+  });
+
+  // initial resize
+  frameResized(doc, delta);
+}
+
+function frameResized(doc, delta) {
+  var frameHeight = $(window).height();
+  if ($.browser.mozilla) frameHeight--;
+  newHeight = frameHeight - delta;
+  //console.debug('frameHeight: %s', frameHeight);
+  //console.debug('delta: %s', delta);
+  //console.debug('newHeight: %s', newHeight);
+  if (newHeight > 50)
+    doc.height(newHeight);
+}
+
+function highlightUrlHash() {
+  //console.debug('window.location.href: %s', window.location.href);
+  var h = window.location.hash;
+  if (h && h != '') {
+    highlightElement(h);
+  }
+};
+
+function highlightTarget(e) {
+  var href = $(e.target).attr('href');
+  //console.debug('Highlighting link href=%s', href);
+  var match =/(#.*)/.exec(href);
+  if (match && match[1].length > 1) {
+    highlightElement(match[1]);
+  }
+};
+
+function highlightElement(id) {
+  //console.debug('Highlighting %s.', id);
+  $('.highlighted').removeClass('highlighted');
+  var e = $(id);
+  if (e.length > 0) {
+    e.addClass('highlighted');
+    //console.debug('added class "highlighted" to %s.', id);
+  }
+  else {
+    //console.debug('not found: %s', id);
+  }
+};
+
+$(document).ready( function() {
+  setupShowSource();
+  setupShowConstantValue();
+  setupShowAllFiles();
+  //setupResizing();  interferes with hyperlinking
+  highlightUrlHash();
+  $('a[href*="#"]').click(highlightTarget);
+});

data/lib/rdoc_babel.rb

@@ -0,0 +1,3 @@
+module RDocBabel
+  VERSION = '0.9.1'
+end

data/test/data/HISTORY.rdoc

@@ -0,0 +1,2 @@
+
+This is HISTORY.

data/test/data/README.rdoc

@@ -0,0 +1,2 @@
+
+This is README.

data/test/data/ancestors.rb

@@ -0,0 +1,42 @@
+
+module Kernel
+  def met; end
+end
+
+class Object
+  def mut; end
+end
+
+module Mod1
+  # doc
+  def met; end
+  def nod; end
+  def mot; end
+end
+
+module Mod2
+  include Mod1
+  # doc
+  def met; end
+end
+
+module Mod3
+  include Mod2
+  def met; end
+  def nod; end
+  def mot; end  # rdoc bug
+end
+
+module Mod4
+  # doc
+  def met; end
+end
+
+class Klass
+  include Mod1
+  include Mod4
+  def met; end
+  def mut; end
+  alias ali met
+  alias ald nod
+end

data/test/data/commented.rb

@@ -0,0 +1,2 @@
+
+# This file contains a comment.

data/test/data/context_alias.rb

@@ -0,0 +1,8 @@
+
+module Mod1
+  def met; end
+end
+
+module Mod2
+  Mod3 = Mod1
+end

data/test/data/main_file.rb

@@ -0,0 +1,15 @@
+
+#--
+# This file will be displayed by default if designated
+# as --main, even though the file itself has no comment.
+
+module RDocBabel
+
+  module NotDocumented
+  end
+
+  # This module should be the first displayed.
+  module Documented
+  end
+
+end

data/test/data/no_class_nor_module.rb

@@ -0,0 +1,2 @@
+
+puts "Hello"

data/test/data/no_content.rb

@@ -0,0 +1,3 @@
+
+module RDocBabel
+end

data/test/data/not_commented.rb

@@ -0,0 +1,10 @@
+
+module RDocBabel
+end
+
+module RDocBabelNoContent
+end
+
+module RDocBabelWithContent
+  CONST = 'const'
+end

data/test/test_rdoc_generator_babel.rb

@@ -0,0 +1,251 @@
+require 'rubygems'
+require 'rdoc/generator/babel'
+require 'minitest/autorun'
+require 'tmpdir'
+require 'nokogiri'
+
+class TestRDocGeneratorBabel < MiniTest::Unit::TestCase
+
+  def setup
+
+    @srcdir = File.expand_path(File.join(File.dirname(__FILE__), 'data'))
+
+    @tmpdir = Dir.mktmpdir('rdoc_babel_')
+    @delete = true
+    @dirnum = 0
+
+    @main = 'README.rdoc'
+    @title = 'Babel Test'
+    @charset = 'utf-8'
+
+  end
+
+  def teardown
+    FileUtils.remove_entry_secure @tmpdir if @delete
+  end
+
+  def test_index
+
+    make_doc %w(--title Hi --charset iso-8859-1 main_file.rb)
+    doc = html_doc('index.html')
+
+    assert_equal 'Hi', doc.at_css('title').content
+    assert_equal 'iso-8859-1', doc.encoding
+
+  end
+
+  def test_first_page
+
+    # - The file designated by the +main_page+ option,
+    #   if there is a +TopLevel+ with that name.
+
+    make_doc %w(--main main_file.rb README.rdoc main_file.rb)
+    assert_main 'files/main_file_rb.html'
+
+    make_doc %w(--main does_not_exist.rdoc README.rdoc main_file.rb)
+    assert_main 'files/README_rdoc.html'
+
+    # - The first simple file that contains a comment
+    #   (in the order given on the command line).
+
+    make_doc %w(README.rdoc HISTORY.rdoc main_file.rb)
+    assert_main 'files/README_rdoc.html'
+
+    # - The first class or module that contains a comment.
+
+    make_doc %w(main_file.rb)
+    assert_main 'classes/RDocBabel/Documented.html'
+
+    # - The first file that contains a comment
+    #   (in the order given on the command line).
+
+    make_doc %w(not_commented.rb commented.rb)
+    assert_main 'files/commented_rb.html'
+
+    # - The first class or module that has any kind of content.
+
+    make_doc %w(not_commented.rb)
+    assert_main 'classes/RDocBabelWithContent.html'
+
+    # - The first class or module.
+
+    make_doc %w(no_content.rb)
+    assert_main 'classes/RDocBabel.html'
+
+    # - The first file.
+
+    make_doc %w(no_class_nor_module.rb)
+    assert_main 'files/no_class_nor_module_rb.html'
+
+  end
+
+  def test_indexes
+
+    make_doc %w(README.rdoc context_alias.rb)
+    doc = html_doc('indexes.html')
+
+    files = doc.at_css('#file-index')
+    assert files, 'file index not found'
+
+    refs = files.css('a')
+    assert_equal 1, refs.length
+    assert_equal 'README.rdoc', refs.first.content
+    assert_equal 'files/README_rdoc.html', refs.first['href']
+
+    classes = doc.at_css('#class-index')
+    assert classes, 'class index not found'
+
+    refs = classes.css('a')
+    assert_equal 3, refs.length
+    assert_equal "Mod2::Mod3 \342\206\222 Mod1", refs.last.content
+    assert_equal 'classes/Mod1.html', refs.last['href']
+
+    methods = doc.at_css('#method-index')
+    assert methods, 'method index not found'
+
+    refs = methods.css('a')
+    assert_equal 1, refs.length
+    assert_equal 'met (Mod1)', refs.first.content
+    assert_equal 'classes/Mod1.html#method-i-met', refs.first['href']
+
+  end
+
+  def test_description
+
+    #@delete = false
+    make_doc %w(ancestors.rb)
+
+    doc = html_doc('classes/Klass.html')
+
+    ali = doc.at_css('#method-i-ali')
+    assert ali, 'Klass#ali not found'
+    assert ali['class'].include?('method-alias'), 'Klass#ali CSS class missing'
+    assert ali.content.include?('Alias for'), 'Klass#ali alias text missing'
+
+    met = doc.at_css('#method-i-met')
+    assert met, 'Klass#met not found'
+    assert met.content.include?('See'), 'Klass#met "see" missing'
+    assert met.content.include?('aliased'), 'Klass#met "aliased" missing'
+
+    mut = doc.at_css('#method-i-mut')
+    assert mut, 'Klass#mut not found'
+    refute mut.content.include?('See'), 'Klass#mut "see" for Object'
+
+    doc = html_doc('classes/Mod1.html')
+
+    met = doc.at_css('#method-i-met')
+    assert met, 'Mod1#met not found'
+    refute met.content.include?('See'), 'Mod1#met "see" for Kernel'
+
+  end
+
+  def test_see_standard_ancestors
+
+    make_doc %w(--see-standard-ancestors ancestors.rb)
+
+    doc = html_doc('classes/Klass.html')
+
+    mut = doc.at_css('#method-i-mut')
+    assert mut, 'Klass#mut not found'
+    assert mut.content.include?('See'), 'Klass#mut "see" for Object'
+
+    doc = html_doc('classes/Mod1.html')
+
+    met = doc.at_css('#method-i-met')
+    assert met, 'Mod1#met not found'
+    assert met.content.include?('See'), 'Mod1#met "see" for Kernel'
+
+  end
+
+  def test_decorated_call_seq
+
+    check_call_seq 'try_convert', <<-CALL, <<-HTML.strip
+      IO.try_convert(obj)  ->  io or nil
+    CALL
+      IO.<span class="c">try_convert</span>(obj)  &rarr;  io or nil
+    HTML
+
+    check_call_seq '<<', <<-CALL, <<-HTML.strip
+      ios << obj     -> ios
+    CALL
+      ios <span class=\"c\">&lt;&lt;</span> obj     &rarr; ios
+    HTML
+
+    check_call_seq 'pos', <<-CALL, <<-HTML.strip.gsub("\n", '')
+      ios.pos     -> integer
+      ios.tell    -> integer
+    CALL
+      ios.<span class=\"c\">pos</span>     &rarr; integer<br/>
+      ios.tell    &rarr; integer
+    HTML
+
+    check_call_seq 'readpartial', <<-CALL, <<-HTML.strip.gsub("\n", '')
+      ios.readpartial(maxlen) -> string
+      ios.readpartial(maxlen, outbuf) -> outbuf
+    CALL
+      ios.<span class=\"c\">readpartial</span>(maxlen) &rarr; string<br/>
+      ios.<span class=\"c\">readpartial</span>(maxlen, outbuf) &rarr; outbuf
+    HTML
+
+    check_call_seq '[]', <<-CALL, <<-HTML.strip.gsub("\n", '')
+      array[index]                - obj      or nil
+      array[start, length]        - an_array or nil
+      array[range]                - an_array or nil
+      array.slice(index)          - obj      or nil
+      array.slice(start, length)  - an_array or nil
+      array.slice(range)          - an_array or nil
+    CALL
+      array<span class=\"c\">[</span>index<span class=\"c\">]</span>                - obj      or nil<br/>
+      array<span class=\"c\">[</span>start, length<span class=\"c\">]</span>        - an_array or nil<br/>
+      array<span class=\"c\">[</span>range<span class=\"c\">]</span>                - an_array or nil<br/>
+      array.slice(index)          - obj      or nil<br/>
+      array.slice(start, length)  - an_array or nil<br/>
+      array.slice(range)          - an_array or nil
+    HTML
+
+  end
+
+private
+
+  def make_doc(args)
+    Dir.chdir(@srcdir) do
+      @dirnum += 1
+      @docdir = File.join(@tmpdir, "doc_#@dirnum")
+      args = [
+        '--quiet',
+        '--op', @docdir,
+        '--format', 'babel',
+      ] + args
+      @rdoc = RDoc::RDoc.new
+      @rdoc.document args
+    end
+
+  end
+
+  def check_call_seq(name, call_seq, html)
+    m = RDoc::AnyMethod.new(nil, name)
+    m.call_seq = call_seq
+    assert_equal html, babel_gen.decorated_call_seq(m, 'c')
+  end
+
+  def babel_gen
+    @babel_gen ||= begin
+      options = Struct.new(:babel_options, :line_numbers, :template).new
+      options.template = 'babel'
+      options.babel_options = {}
+      RDoc::Generator::Babel.new(options)
+    end
+  end
+
+  def assert_main(expected_file)
+    doc = html_doc('index.html')
+    main_frame = doc.at_css 'frame[name = "mainFrame"]'
+    assert_equal expected_file, main_frame['src'], "assert_main ##@dirnum"
+  end
+
+  def html_doc(file)
+    file = File.join(@docdir, file)
+    File.open(file, 'rb') { |f| Nokogiri.HTML f }
+  end
+
+end

metadata

@@ -0,0 +1,167 @@
+--- !ruby/object:Gem::Specification 
+name: rdoc-babel
+version: !ruby/object:Gem::Version 
+  hash: 57
+  prerelease: 
+  segments: 
+  - 0
+  - 9
+  - 1
+  version: 0.9.1
+platform: ruby
+authors: 
+- Thierry Lambert
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-07-17 00:00:00 Z
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rdoc
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 7
+        segments: 
+        - 3
+        - 0
+        version: "3.0"
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: minitest
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 1
+        segments: 
+        - 1
+        - 7
+        version: "1.7"
+  type: :development
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: nokogiri
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 7
+        segments: 
+        - 1
+        - 4
+        version: "1.4"
+  type: :development
+  version_requirements: *id003
+- !ruby/object:Gem::Dependency 
+  name: hoe
+  prerelease: false
+  requirement: &id004 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 23
+        segments: 
+        - 2
+        - 10
+        version: "2.10"
+  type: :development
+  version_requirements: *id004
+description: |-
+  Babel is an RDoc formatter producing HTML documentation.
+  The default template is +ruby-lang+.
+  
+  - 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.
+email: 
+- thyresias@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- Manifest.txt
+- README.rdoc
+- HISTORY.rdoc
+files: 
+- .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
+- .gemtest
+homepage: http://github.com/thyresias/babel
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --main
+- README.rdoc
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: rdoc-babel
+rubygems_version: 1.8.5
+signing_key: 
+specification_version: 3
+summary: An RDoc formatter producing HTML documentation.
+test_files: 
+- test/test_rdoc_generator_babel.rb