Fix ref links in main page

jonathanhefner · jonathanhefner · commit d0ce1ca00c78 · 2023-08-17T16:32:24.000-05:00
The main page reuses an already-processed file.  All of the ref links in
that file will be rendered relative to its path rather than relative to
the root.  For example, ref links in `railties/RDOC_MAIN.md` will be
relative to `files/railties/`, so a link to `ActiveRecord::Base` would
use `../../ActiveRecord/Base.html` instead of `ActiveRecord/Base.html`.

This commit changes `RDoc::Generator::SDoc#index` to dup the processed
file and override its `path` value such that links on the main page use
the root-relative path (but links on the file's page will still use the
`files/`-relative path).

This change also makes it unnecessary to escape occurrences of "Rails"
in the main page because, with the correct `href`, the postprocessor
will now recognize them as unintentional ref links.
diff --git a/lib/rdoc/generator/template/rails/index.rhtml b/lib/rdoc/generator/template/rails/index.rhtml
@@ -4,7 +4,7 @@
     <meta charset="<%= @options.charset %>">
     <title><%= page_title %></title>
     <meta name="viewport" content="width=device-width,initial-scale=1">
-    <%= include_template '_head.rhtml', {:context => nil, tree_keys: []} %>
+    <%= include_template '_head.rhtml', {:context => index, tree_keys: []} %>
 </head>
 
 <body>
diff --git a/lib/sdoc/generator.rb b/lib/sdoc/generator.rb
@@ -8,6 +8,14 @@
 require 'sdoc/version'
 require 'rdoc'
 
+RDoc::TopLevel.prepend(Module.new do
+  attr_writer :path
+
+  def path
+    @path ||= super
+  end
+end)
+
 class RDoc::ClassModule
   def with_documentation?
     document_self_or_methods || classes_and_modules.any?{ |c| c.with_documentation? }
@@ -122,10 +130,16 @@ def file_dir
 
   ### Determines index page based on @options.main_page (or lack thereof)
   def index
-    path = @original_dir.join(@options.main_page || @options.files.first || "")
-    file = @files.find { |file| @options.root.join(file.full_name) == path }
-    raise "Could not find main page #{path.to_s.inspect} among rendered files" if !file
-    file
+    @index ||= begin
+      path = @original_dir.join(@options.main_page || @options.files.first || "")
+      file = @files.find { |file| @options.root.join(file.full_name) == path }
+      raise "Could not find main page #{path.to_s.inspect} among rendered files" if !file
+
+      file = file.dup
+      file.path = ""
+
+      file
+    end
   end
 
   protected
diff --git a/lib/sdoc/helpers.rb b/lib/sdoc/helpers.rb
@@ -36,8 +36,8 @@ def full_name(named)
   end
 
   def base_tag_for_context(context)
-    relative_root = "../" * context.path.count("/") if context
-    %(<base href="./#{relative_root}" data-current-path="#{context&.path}">)
+    relative_root = "../" * context.path.count("/")
+    %(<base href="./#{relative_root}" data-current-path="#{context.path}">)
   end
 
   def canonical_url(path = nil)
diff --git a/spec/helpers_spec.rb b/spec/helpers_spec.rb
@@ -196,11 +196,6 @@ module Foo; module Bar; class Qux; end; end; end
   end
 
   describe "#base_tag_for_context" do
-    it "returns an idempotent <base> tag for nil context" do
-      _(@helpers.base_tag_for_context(nil)).
-        must_equal %(<base href="./" data-current-path="">)
-    end
-
     it "returns a <base> tag with an appropriate path for the given RDoc::Context" do
       top_level = rdoc_top_level_for <<~RUBY
         module Foo; module Bar; module Qux; end; end; end
diff --git a/spec/rdoc_generator_spec.rb b/spec/rdoc_generator_spec.rb
@@ -123,5 +123,13 @@ def parse_options(*options)
       sdoc = rdoc_dry_run("--main", @files.first, "--files", *@files).generator
       _(sdoc.index.absolute_name).must_equal @files.first
     end
+
+    it "overrides RDoc::TopLevel#path" do
+      Dir.chdir(@dir) do
+        sdoc = rdoc_dry_run("--files", *@files).generator
+        _(sdoc.index.path).must_equal ""
+        sdoc.store.all_files.each { |file| _(file.path).wont_equal "" }
+      end
+    end
   end
 end
