From 3a4e10772c3e20711d8e3bf0b8a9f4907c3b2703 Mon Sep 17 00:00:00 2001 From: st0012 Date: Mon, 23 Feb 2026 11:23:44 +0000 Subject: [PATCH 1/2] Stop generating a separate page file for main_page 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 --- lib/rdoc/generator/darkfish.rb | 2 ++ lib/rdoc/generator/json_index.rb | 2 +- .../template/aliki/_sidebar_pages.rhtml | 2 +- test/rdoc/generator/darkfish_test.rb | 16 ++++++++++++++++ 4 files changed, 20 insertions(+), 2 deletions(-) diff --git a/lib/rdoc/generator/darkfish.rb b/lib/rdoc/generator/darkfish.rb index 9a81b74688..f30c061979 100644 --- a/lib/rdoc/generator/darkfish.rb +++ b/lib/rdoc/generator/darkfish.rb @@ -393,6 +393,8 @@ def generate_file_files @files.each do |file| current = file + next if file.full_name == @options.main_page + if file.text? and page_file.exist? then generate_page file next diff --git a/lib/rdoc/generator/json_index.rb b/lib/rdoc/generator/json_index.rb index c61391d630..065419b296 100644 --- a/lib/rdoc/generator/json_index.rb +++ b/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| diff --git a/lib/rdoc/generator/template/aliki/_sidebar_pages.rhtml b/lib/rdoc/generator/template/aliki/_sidebar_pages.rhtml index 94004ae7e1..c6b61364e7 100644 --- a/lib/rdoc/generator/template/aliki/_sidebar_pages.rhtml +++ b/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 %> diff --git a/test/rdoc/generator/darkfish_test.rb b/test/rdoc/generator/darkfish_test.rb index ddce14632e..eca8752af0 100644 --- a/test/rdoc/generator/darkfish_test.rb +++ b/test/rdoc/generator/darkfish_test.rb @@ -178,6 +178,22 @@ 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_index_without_main_page top_level = @store.add_file 'file.rb' top_level.comment = <<~RDOC From e42e8334710db610d843b0afd19fd85612c1f7ab Mon Sep 17 00:00:00 2001 From: st0012 Date: Mon, 23 Feb 2026 21:56:41 +0000 Subject: [PATCH 2/2] Make all links to main_page point to index.html When a page is set as main_page, its content is displayed on index.html and no separate page file is generated. Update TopLevel#path to return index.html for the main_page so all consumers (cross-references, sidebar links, table of contents, search records) automatically generate correct links. Also tighten the generate_file_files skip to only apply to text pages, preventing accidental skipping if a source file is set as main_page. --- lib/rdoc/code_object/top_level.rb | 10 +++- lib/rdoc/generator/darkfish.rb | 2 +- test/rdoc/generator/darkfish_test.rb | 38 ++++++++++++++ test/rdoc/generator/json_index_test.rb | 16 ++++++ test/rdoc/markup/to_html_crossref_test.rb | 35 +++++++++++++ test/rdoc/rdoc_top_level_test.rb | 60 +++++++++++++++++++++++ 6 files changed, 158 insertions(+), 3 deletions(-) diff --git a/lib/rdoc/code_object/top_level.rb b/lib/rdoc/code_object/top_level.rb index 21e412f82a..2bb2767c89 100644 --- a/lib/rdoc/code_object/top_level.rb +++ b/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: diff --git a/lib/rdoc/generator/darkfish.rb b/lib/rdoc/generator/darkfish.rb index f30c061979..e3f45deeab 100644 --- a/lib/rdoc/generator/darkfish.rb +++ b/lib/rdoc/generator/darkfish.rb @@ -393,7 +393,7 @@ def generate_file_files @files.each do |file| current = file - next if file.full_name == @options.main_page + next if file.text? && file.full_name == @options.main_page if file.text? and page_file.exist? then generate_page file diff --git a/test/rdoc/generator/darkfish_test.rb b/test/rdoc/generator/darkfish_test.rb index eca8752af0..bf4ec57058 100644 --- a/test/rdoc/generator/darkfish_test.rb +++ b/test/rdoc/generator/darkfish_test.rb @@ -194,6 +194,44 @@ def test_generate_does_not_create_page_file_for_main_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{README}, other_html + assert_not_match %r{README}, other_html + end + def test_generate_index_without_main_page top_level = @store.add_file 'file.rb' top_level.comment = <<~RDOC diff --git a/test/rdoc/generator/json_index_test.rb b/test/rdoc/generator/json_index_test.rb index 6157b49881..062e6a19d6 100644 --- a/test/rdoc/generator/json_index_test.rb +++ b/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 diff --git a/test/rdoc/markup/to_html_crossref_test.rb b/test/rdoc/markup/to_html_crossref_test.rb index 9366de861e..802acb7063 100644 --- a/test/rdoc/markup/to_html_crossref_test.rb +++ b/test/rdoc/markup/to_html_crossref_test.rb @@ -84,6 +84,13 @@ def test_convert_CROSSREF_label_for_md assert_equal para("foo at EXAMPLE"), result end + def test_convert_CROSSREF_label_for_main_page + @options.main_page = 'EXAMPLE.md' + + result = @to.convert 'EXAMPLE@foo' + assert_equal para("foo at EXAMPLE"), result + end + def test_convert_CROSSREF_label_period result = @to.convert 'C1@foo.' assert_equal para("foo at C1."), result @@ -299,6 +306,20 @@ def test_handle_regexp_HYPERLINK_rdoc assert_equal 'README.txt', 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 'README.txt', 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 'tidy', 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 'tidy', link + end + def test_handle_regexp_TIDYLINK_label link = @to.to_html tidy 'C1#m@foo' diff --git a/test/rdoc/rdoc_top_level_test.rb b/test/rdoc/rdoc_top_level_test.rb index a785abf06e..57be520b86 100644 --- a/test/rdoc/rdoc_top_level_test.rb +++ b/test/rdoc/rdoc_top_level_test.rb @@ -157,6 +157,16 @@ 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 @@ -164,6 +174,36 @@ def test_path 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', + '', + "

This is a comment.\n", + ] + + assert_equal expected, page.search_record + end + def test_text_eh refute @xref_data.text?