From 8d18c1e9e2dc731989a729bb8dc27cc22e5110b5 Mon Sep 17 00:00:00 2001
From: Petrik <petrik@deheus.net>
Date: Wed, 17 Jan 2024 13:08:53 +0100
Subject: [PATCH] Include files relative to the framework root

The Rails documentation uses the `:include:` directive to inline the
README of the framework into the main documentation page.
As the README's aren't in the root directory from where SDoc is run we
need to add the framework path to the include:

    # :include: activesupport/README.md

This results in a warning when installing the gems as generating the
rdoc for the gem is run from the gem/framework root:

    Couldn't find file to include 'activesupport/README.rdoc' from lib/active_support.rb

By Monkeypatching `find_include_file` to find files at the framework
root we can include without the framework path:

    # :include: README.md
---
 lib/sdoc/rdoc_monkey_patches.rb  | 12 ++++++++++++
 spec/rdoc_monkey_patches_spec.rb | 24 ++++++++++++++++++++++++
 2 files changed, 36 insertions(+)

diff --git a/lib/sdoc/rdoc_monkey_patches.rb b/lib/sdoc/rdoc_monkey_patches.rb
index ce858e5e..146df850 100644
--- a/lib/sdoc/rdoc_monkey_patches.rb
+++ b/lib/sdoc/rdoc_monkey_patches.rb
@@ -60,3 +60,15 @@ def record_location(*)
     super unless @ignoring_constants
   end
 end)
+
+RDoc::Markup::PreProcess.prepend(Module.new do
+  def find_include_file(name)
+    to_search = [File.dirname(@input_file_name, 2)].concat @include_path
+    to_search.each do |dir|
+      full_name = File.join(dir, name)
+      stat = File.stat(full_name) rescue next
+      return full_name if stat.readable?
+    end
+    nil
+  end
+end)
diff --git a/spec/rdoc_monkey_patches_spec.rb b/spec/rdoc_monkey_patches_spec.rb
index bd980c52..c7b3d373 100644
--- a/spec/rdoc_monkey_patches_spec.rb
+++ b/spec/rdoc_monkey_patches_spec.rb
@@ -114,4 +114,28 @@ def foo; Float::INFINITY; end
       end
     end
   end
+
+  describe RDoc::Markup::PreProcess do
+    it "includes files relative to the framework root" do
+      Dir.mktmpdir do |dir|
+        Dir.chdir(dir) do
+          FileUtils.mkdir_p("railties/lib")
+          File.write("railties/lib/rails.rb", <<~RUBY)
+            # :include: README.md
+            module Rails
+            end
+          RUBY
+
+          File.write("railties/README.md", <<~RUBY)
+            Railties - Gluing the Engine to the Rails
+          RUBY
+
+          rdoc_store = rdoc_dry_run("--files", "railties/lib/rails.rb", "railties/README.md").store
+
+          _(rdoc_store.find_class_or_module("Rails").description).
+            must_match %r"Railties - Gluing the Engine to the Rails"
+        end
+      end
+    end
+  end
 end