Stop generating a separate page file for main_page (#1624)

When a page is used as `main_page` (e.g. `README.md`), its content is
already displayed on index.html. Generating a separate page file (e.g.
`README_md.html`) is redundant.

Skip the main_page in:
- darkfish generator (page file generation)
- json search index (avoids linking to a nonexistent page)
- aliki sidebar pages template

Author: st0012

lib/rdoc/code_object/top_level.rb

@@ -221,9 +221,15 @@ def object_class
   # Path to this file for use with HTML generator output.
 
   def path
+    base = if options.main_page == full_name
+             'index.html'
+           else
+             http_url
+           end
+
     prefix = options.file_path_prefix
-    return http_url unless prefix
-    File.join(prefix, http_url)
+    return base unless prefix
+    File.join(prefix, base)
   end
 
   def pretty_print(q) # :nodoc:

lib/rdoc/generator/darkfish.rb

@@ -393,6 +393,8 @@ def generate_file_files
     @files.each do |file|
       current = file
 
+      next if file.text? && file.full_name == @options.main_page
+
       if file.text? and page_file.exist? then
         generate_page file
         next

lib/rdoc/generator/json_index.rb

@@ -250,7 +250,7 @@ def index_pages
     debug_msg "  generating pages search index"
 
     pages = @files.select do |file|
-      file.text?
+      file.text? && file.full_name != @options.main_page
     end
 
     pages.each do |page|

lib/rdoc/generator/template/aliki/_sidebar_pages.rhtml

@@ -1,4 +1,4 @@
-<%- simple_files = @files.select { |f| f.text? } %>
+<%- simple_files = @files.select { |f| f.text? && f.full_name != @options.main_page } %>
 
 <%- if defined?(current) && current.respond_to?(:page_name) %>
   <%- dir = current.full_name[%r{\A[^/]+(?=/)}] || current.page_name %>

test/rdoc/generator/darkfish_test.rb

@@ -178,6 +178,60 @@ def test_generate_index_with_main_page
     assert_not_include index_html, 'This is the API documentation for My awesome Ruby project.'
   end
 
+  def test_generate_does_not_create_page_file_for_main_page
+    top_level = @store.add_file("README.rdoc", parser: RDoc::Parser::Simple)
+    top_level.comment = "= Main Page\nThis is the main page content."
+
+    other_page = @store.add_file("OTHER.rdoc", parser: RDoc::Parser::Simple)
+    other_page.comment = "= Other Page\nThis is another page."
+
+    @options.main_page = "README.rdoc"
+
+    @g.generate
+
+    assert_file "index.html"
+    refute File.exist?("README_rdoc.html"), "main_page should not be generated as a separate page"
+    assert_file "OTHER_rdoc.html"
+  end
+
+  def test_generate_sidebar_links_main_page_to_index_html
+    top_level = @store.add_file("README.rdoc", parser: RDoc::Parser::Simple)
+    top_level.comment = "= Main Page\nThis is the main page content."
+
+    other_page = @store.add_file("OTHER.rdoc", parser: RDoc::Parser::Simple)
+    other_page.comment = "= Other Page\nThis is another page."
+
+    @options.main_page = "README.rdoc"
+    @store.options.main_page = "README.rdoc"
+
+    @g.generate
+
+    other_html = File.binread("OTHER_rdoc.html")
+
+    # The sidebar should link README to index.html, not README_rdoc.html
+    assert_match %r{href="[^"]*index\.html"[^>]*>\s*README}m, other_html
+    assert_not_match %r{href="[^"]*README_rdoc\.html"}, other_html
+  end
+
+  def test_generate_cross_reference_to_main_page_links_to_index_html
+    readme = @store.add_file("README.rdoc", parser: RDoc::Parser::Simple)
+    readme.comment = "= Main Page\nThis is the main page content."
+
+    other_page = @store.add_file("OTHER.rdoc", parser: RDoc::Parser::Simple)
+    other_page.comment = "= Other Page\nSee README.rdoc for more info."
+
+    @options.main_page = "README.rdoc"
+    @store.options.main_page = "README.rdoc"
+
+    @g.generate
+
+    other_html = File.binread("OTHER_rdoc.html")
+
+    # Cross-reference to main_page should point to index.html
+    assert_match %r{<a href="[^"]*index\.html">README</a>}, other_html
+    assert_not_match %r{<a href="[^"]*README_rdoc\.html">README</a>}, other_html
+  end
+
   def test_generate_index_without_main_page
     top_level = @store.add_file 'file.rb'
     top_level.comment = <<~RDOC

test/rdoc/generator/json_index_test.rb

@@ -356,6 +356,22 @@ def test_index_pages
     assert_equal expected, @g.index
   end
 
+  def test_index_pages_excludes_main_page
+    @options.main_page = "page.rdoc"
+
+    @g.reset @top_levels, @klasses
+
+    @g.index_pages
+
+    expected = {
+      searchIndex:     [],
+      longSearchIndex: [],
+      info:            [],
+    }
+
+    assert_equal expected, @g.index
+  end
+
   def test_search_string
     assert_equal 'cd', @g.search_string('C d')
   end

test/rdoc/markup/to_html_crossref_test.rb

@@ -84,6 +84,13 @@ def test_convert_CROSSREF_label_for_md
     assert_equal para("<a href=\"EXAMPLE_md.html#foo\">foo at <code>EXAMPLE</code></a>"), result
   end
 
+  def test_convert_CROSSREF_label_for_main_page
+    @options.main_page = 'EXAMPLE.md'
+
+    result = @to.convert 'EXAMPLE@foo'
+    assert_equal para("<a href=\"index.html#foo\">foo at <code>EXAMPLE</code></a>"), result
+  end
+
   def test_convert_CROSSREF_label_period
     result = @to.convert 'C1@foo.'
     assert_equal para("<a href=\"C1.html#class-c1-foo\">foo at <code>C1</code></a>."), result
@@ -299,6 +306,20 @@ def test_handle_regexp_HYPERLINK_rdoc
     assert_equal '<a href="README_txt.html">README.txt</a>', link
   end
 
+  def test_handle_regexp_HYPERLINK_rdoc_main_page
+    readme = @store.add_file 'README.txt'
+    readme.parser = RDoc::Parser::Simple
+
+    @options.main_page = 'README.txt'
+
+    @to = RDoc::Markup::ToHtmlCrossref.new 'C2.html', @c2,
+      hyperlink_all: true, warn_missing_rdoc_ref: true
+
+    link = @to.handle_regexp_HYPERLINK hyper 'README.txt'
+
+    assert_equal '<a href="index.html">README.txt</a>', link
+  end
+
   def test_handle_TIDYLINK_rdoc
     readme = @store.add_file 'README.txt'
     readme.parser = RDoc::Parser::Simple
@@ -323,6 +344,20 @@ def test_handle_TIDYLINK_rdoc
     assert_equal '<a href="README_txt.html">tidy</a>', link
   end
 
+  def test_handle_TIDYLINK_rdoc_main_page
+    readme = @store.add_file 'README.txt'
+    readme.parser = RDoc::Parser::Simple
+
+    @options.main_page = 'README.txt'
+
+    @to = RDoc::Markup::ToHtmlCrossref.new 'C2.html', @c2,
+      hyperlink_all: true, warn_missing_rdoc_ref: true
+
+    link = @to.to_html tidy 'README.txt'
+
+    assert_equal '<a href="index.html">tidy</a>', link
+  end
+
   def test_handle_regexp_TIDYLINK_label
     link = @to.to_html tidy 'C1#m@foo'
 

test/rdoc/rdoc_top_level_test.rb

@@ -157,13 +157,53 @@ def test_http_url
     assert_equal 'path_other/level_rb.html', other_level.http_url
   end
 
+  def test_http_url_unaffected_by_main_page
+    page = @store.add_file 'README.md'
+    page.parser = RDoc::Parser::Simple
+
+    @store.main = 'README.md'
+
+    # http_url always returns the file-based URL; main_page redirect is in #path
+    assert_equal 'README_md.html', page.http_url
+  end
+
   def test_path
     assert_equal 'path/top_level_rb.html', @top_level.path
 
     @options.file_path_prefix = 'file'
     assert_equal 'file/path/top_level_rb.html', @top_level.path
   end
 
+  def test_path_main_page
+    page = @store.add_file 'README.md'
+    page.parser = RDoc::Parser::Simple
+
+    @options.main_page = 'README.md'
+
+    assert_equal 'index.html', page.path
+  end
+
+  def test_path_main_page_with_prefix
+    page = @store.add_file 'README.md'
+    page.parser = RDoc::Parser::Simple
+
+    @options.main_page = 'README.md'
+    @options.file_path_prefix = 'file'
+
+    assert_equal 'file/index.html', page.path
+  end
+
+  def test_path_non_main_page_unaffected
+    page = @store.add_file 'README.md'
+    page.parser = RDoc::Parser::Simple
+    other = @store.add_file 'OTHER.md'
+    other.parser = RDoc::Parser::Simple
+
+    @options.main_page = 'README.md'
+
+    assert_equal 'OTHER_md.html', other.path
+  end
+
   def test_marshal_dump
     page = @store.add_file 'README.txt'
     page.parser = RDoc::Parser::Simple
@@ -259,6 +299,26 @@ def test_search_record_page
     assert_equal expected, page.search_record
   end
 
+  def test_search_record_main_page
+    page = @store.add_file 'README.txt'
+    page.parser = RDoc::Parser::Simple
+    page.comment = 'This is a comment.'
+
+    @options.main_page = 'README.txt'
+
+    expected = [
+      'README',
+      '',
+      'README',
+      '',
+      'index.html',
+      '',
+      "<p>This is a comment.\n",
+    ]
+
+    assert_equal expected, page.search_record
+  end
+
   def test_text_eh
     refute @xref_data.text?