Display main page's Table of Contents when viewed from the index page (#1250)

When the main page document is viewed as a standalone page, Darkfish
displays the Table of Contents. When viewed from the index page, it does
not.

This page changes the behaviour to also display the Table of Contents
when the main page document is viewed from the index page.

### Before

<img width="60%" alt="Screenshot 2024-12-22 at 16 30 45"
src="https://github.com/user-attachments/assets/8648b9ff-2e39-4ee9-b8c5-6b78f2ed5e55"
/>

### After

<img width="60%" alt="Screenshot 2024-12-22 at 16 31 14"
src="https://github.com/user-attachments/assets/945f0a4a-dbb1-4558-b7a9-9450e94dba4f"
/>

### In `ruby/ruby`


<img width="60%" alt="Screenshot 2024-12-22 at 16 34 10"
src="https://github.com/user-attachments/assets/5d6e1e44-dfc6-4fc0-92f2-737865ec54f4"
/>

Author: st0012

lib/rdoc/generator/darkfish.rb

@@ -316,11 +316,14 @@ def generate_index
     asset_rel_prefix = rel_prefix + @asset_rel_path
 
     @title = @options.title
+    @main_page = @files.find { |f| f.full_name == @options.main_page }
 
     render_template template_file, out_file do |io|
       here = binding
       # suppress 1.9.3 warning
       here.local_variable_set(:asset_rel_prefix, asset_rel_prefix)
+      # some partials rely on the presence of current variable to render
+      here.local_variable_set(:current, @main_page) if @main_page
       here
     end
   rescue => e

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

@@ -7,17 +7,17 @@
     <%= render '_sidebar_search.rhtml' %>
   </div>
 
+  <%= render '_sidebar_table_of_contents.rhtml' if defined?(current) %>
   <%= render '_sidebar_pages.rhtml' %>
   <%= render '_sidebar_classes.rhtml' %>
 
   <%= render '_footer.rhtml' %>
 </nav>
 
 <main role="main">
-<%- if @options.main_page and
-      main_page = @files.find { |f| f.full_name == @options.main_page } then %>
-<%= main_page.description %>
+<%- if @main_page %>
+  <%= @main_page.description %>
 <%- else -%>
-<p>This is the API documentation for <%= h @title %>.
+  <p>This is the API documentation for <%= h @title %>.
 <%- end -%>
 </main>

test/rdoc/test_rdoc_generator_darkfish.rb

@@ -134,6 +134,88 @@ def test_generate
     )
   end
 
+  def test_generate_index_with_main_page
+    top_level = @store.add_file 'file.rb'
+    top_level.comment = <<~RDOC
+    = Heading 1
+    Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod
+    == Heading 1.1
+    tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam,
+    === Heading 1.1.1
+    quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo
+    ==== Heading 1.1.1.1
+    consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse
+    == Heading 1.2
+    cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat
+    == Heading 1.3
+    non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
+    === Heading 1.3.1
+    etc etc...
+    RDOC
+
+    @options.main_page = 'file.rb'
+    @options.title = 'My awesome Ruby project'
+
+    @g.generate
+
+    assert_file 'index.html'
+    assert_file 'table_of_contents.html'
+    assert_file 'js/search_index.js'
+
+    assert_hard_link 'css/rdoc.css'
+    assert_hard_link 'css/fonts.css'
+
+    assert_hard_link 'fonts/SourceCodePro-Bold.ttf'
+    assert_hard_link 'fonts/SourceCodePro-Regular.ttf'
+
+    index_html = File.binread('index.html')
+
+    assert_include index_html, "<h3>Table of Contents</h3>"
+    assert_include index_html, '<h1 id="label-Heading+1">Heading 1'
+    # When there's a main page, the default description should not be shown
+    assert_not_include index_html, 'This is the API documentation for My awesome Ruby project.'
+  end
+
+  def test_generate_index_without_main_page
+    top_level = @store.add_file 'file.rb'
+    top_level.comment = <<~RDOC
+    = Heading 1
+    Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod
+    == Heading 1.1
+    tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam,
+    === Heading 1.1.1
+    quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo
+    ==== Heading 1.1.1.1
+    consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse
+    == Heading 1.2
+    cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat
+    == Heading 1.3
+    non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
+    === Heading 1.3.1
+    etc etc...
+    RDOC
+
+    @options.title = 'My awesome Ruby project'
+
+    @g.generate
+
+    assert_file 'index.html'
+    assert_file 'table_of_contents.html'
+    assert_file 'js/search_index.js'
+
+    assert_hard_link 'css/rdoc.css'
+    assert_hard_link 'css/fonts.css'
+
+    assert_hard_link 'fonts/SourceCodePro-Bold.ttf'
+    assert_hard_link 'fonts/SourceCodePro-Regular.ttf'
+
+    index_html = File.binread('index.html')
+
+    # If there is no main page, the index page should not have a table of contents
+    assert_not_include index_html, "<h3>Table of Contents</h3>"
+    assert_include index_html, 'This is the API documentation for My awesome Ruby project.'
+  end
+
   def test_generate_page
     @store.add_file 'outer.rdoc', parser: RDoc::Parser::Simple
     @store.add_file 'outer/inner.rdoc', parser: RDoc::Parser::Simple