Added sections to the Table of Contents page

Author: drbrain

TODO.rdoc

@@ -1,9 +1,5 @@
 Some file contains some things that might happen in RDoc, or might not
 
-=== RDoc 3.10
-
-* Add sections to the ToC
-
 === RDoc 3.11
 
 * Reload the RDoc tree from an RI store

lib/rdoc/context.rb

@@ -653,7 +653,9 @@ def each_include # :yields: include
   # Iterator for methods
 
   def each_method # :yields: method
-    @method_list.sort.each {|m| yield m}
+    return enum_for __method__ unless block_given?
+
+    @method_list.sort.each { |m| yield m }
   end
 
   ##
@@ -1007,10 +1009,10 @@ def remove_invisible_in array, min_visibility # :nodoc:
   end
 
   ##
-  # Tries to resolve unmatched aliases when a method
-  # or attribute has just been added.
+  # Tries to resolve unmatched aliases when a method or attribute has just
+  # been added.
 
-  def resolve_aliases(added)
+  def resolve_aliases added
     # resolve any pending unmatched aliases
     key = added.pretty_name
     unmatched_alias_list = @unmatched_alias_lists[key]
@@ -1022,6 +1024,31 @@ def resolve_aliases(added)
     @unmatched_alias_lists.delete key
   end
 
+  ##
+  # Returns RDoc::Context::Section objects referenced in this context for use
+  # in a table of contents.
+
+  def section_contents
+    used_sections = {}
+
+    each_method do |method|
+      next unless method.display?
+
+      used_sections[method.section] = true
+    end
+
+    # order found sections
+    sections = sort_sections.select do |section|
+      used_sections[section]
+    end
+
+    # only the default section is used
+    return [] if
+      sections.length == 1 and not sections.first.title
+
+    sections
+  end
+
   ##
   # Sections in this context
 

lib/rdoc/context/section.rb

@@ -102,6 +102,15 @@ def inspect # :nodoc:
     "#<%s:0x%x %p>" % [self.class, object_id, title]
   end
 
+  ##
+  # The section's title, or 'Top Section' if the title is nil.
+  #
+  # This is used by the table of contents template so the name is silly.
+
+  def plain_html
+    @title || 'Top Section'
+  end
+
   ##
   # Section sequence number (deprecated)
 

lib/rdoc/generator/template/darkfish/table_of_contents.rhtml

@@ -8,7 +8,9 @@
 <% simple_files.sort.each do |file| %>
   <li class="file">
     <a href="<%= file.path %>"><%= h file.page_name %></a>
-<% table = file.parse(file.comment).table_of_contents # HACK
+<%
+   # HACK table_of_contents should not exist on Document
+   table = file.parse(file.comment).table_of_contents
    unless table.empty? then %>
     <img class="toc-toggle" src="images/transparent.png" alt="" title="toggle headings">
     <ul class="initially-hidden">
@@ -27,12 +29,15 @@
 <% @modsort.each do |klass| %>
   <li class="<%= klass.type %>">
     <a href="<%= klass.path %>"><%= klass.full_name %></a>
-<% table = klass.parse(klass.comment).table_of_contents # HACK
+<% table = []
+   table.push(*klass.parse(klass.comment).table_of_contents)
+   table.push(*klass.section_contents)
+
    unless table.empty? then %>
     <img class="toc-toggle" src="images/transparent.png" alt="" title="toggle headings">
     <ul class="initially-hidden">
-<% table.each do |heading| %>
-      <li><a href="<%= klass.path %>#<%= heading.label %>"><%= heading.plain_html %></a>
+<% table.each do |item| %>
+      <li><a href="<%= klass.path %>#<%= item.aref %>"><%= item.plain_html %></a>
 <%   end %>
     </ul>
 <% end %>

lib/rdoc/markup/heading.rb

@@ -40,9 +40,9 @@ def accept visitor
   end
 
   ##
-  # An HTML-safe label for this header.
+  # An HTML-safe anchor reference for this header.
 
-  def label
+  def aref
     "label-#{self.class.to_label.convert text.dup}"
   end
 

lib/rdoc/markup/to_html.rb

@@ -268,7 +268,7 @@ def accept_blank_line(blank_line)
   def accept_heading heading
     level = [6, heading.level].min
 
-    label = heading.label
+    label = heading.aref
     label = [@code_object.aref, label].compact.join '-' if
       @code_object and @code_object.respond_to? :aref
 

test/test_rdoc_context.rb

@@ -364,6 +364,10 @@ def test_equals2
     refute_equal @c2_c3, @c3
   end
 
+  def test_each_method_enumerator
+    assert_kind_of Enumerator, @c1.each_method
+  end
+
   def test_each_section
     sects  = []
     consts = []
@@ -392,6 +396,10 @@ def test_each_section
     assert_equal expected_attrs, attrs
   end
 
+  def test_each_section_enumerator
+    assert_kind_of Enumerator, @c1.each_section
+  end
+
   def test_find_attribute_named
     assert_equal nil,  @c1.find_attribute_named('none')
     assert_equal 'R',  @c1.find_attribute_named('attr').rw
@@ -667,6 +675,43 @@ def test_remove_invisible_in_public_force
     assert_equal [@pub, @prot, @priv], methods
   end
 
+  def test_section_contents
+    default = @context.sections.first
+    @context.add_method RDoc::AnyMethod.new(nil, 'm1')
+
+    b = @context.add_section 'B'
+    m = @context.add_method RDoc::AnyMethod.new(nil, 'm2')
+    m.section = b
+
+    assert_equal [default, b], @context.section_contents
+  end
+
+  def test_section_contents_no_default
+    @context = RDoc::Context.new
+    b = @context.add_section 'B'
+    m = @context.add_method RDoc::AnyMethod.new(nil, 'm')
+    m.section = b
+
+    assert_equal [b], @context.section_contents
+  end
+
+  def test_section_contents_only_default
+    @context = RDoc::Context.new
+
+    @context.add_method RDoc::AnyMethod.new(nil, 'm')
+
+    assert_empty @context.section_contents
+  end
+
+  def test_section_contents_unused
+    @context = RDoc::Context.new
+
+    @context.add_method RDoc::AnyMethod.new(nil, 'm')
+    b = @context.add_section 'B'
+
+    assert_empty @context.section_contents
+  end
+
   def test_set_current_section
     default_section = @context.sections.first
 

test/test_rdoc_markup_heading.rb

@@ -8,8 +8,8 @@ def setup
     @h = RDoc::Markup::Heading.new 1, 'Hello *Friend*!'
   end
 
-  def test_label
-    assert_equal 'label-Hello+Friend%21', @h.label
+  def test_aref
+    assert_equal 'label-Hello+Friend%21', @h.aref
   end
 
   def test_plain_html