Make it loose coupling between RubyGems and RDoc (#1171)

* Make it loose coupling between RubyGems and RDoc

\### Problems

There are following problems because of tight coupling between RubyGems and RDoc.

1. If there are braking changes in RDoc, RubyGems is also broken.
2. When we maintain RDoc, we have to change RubyGems.

The reason why they are happened is that RubyGems creates documents about a gem with installing it.

Note that RubyGems uses functions of RDoc to create documents.
Specifically,

- Creating documents is executed by `rubygems/lib/rubygems/rdoc.rb`.
- `::RDoc::RubygemsHook` which is defined by RDoc is called by the file.

\### Solution

RubyGems has the plugin system.

If a gem includes `rubygems_plugin.rb`, RubyGems loads it.
RubyGems executes a process defined in it while installing gems, uninstalling gems or other events.

We can use the system to solve the problems.

The root cause is RubyGems directly references the class of RDoc.

We can remove the root cause by making RDoc RubyGems plugin.

Alternatively `rubygems_plugin.rb` creates documents about gems.

\### FAQ

Q1. Do we need to change codes of RubyGems?

A.

No, we don't.

This change keeps compatibility of API used from RubyGems.

Q2. Is it better to delete existing codes related to RDoc in RubyGems?

No, it isn't.

If we change codes of RubyGems,
we can't keep a compatibility.

Example:

If we delete codes that uses `RDoc::RubygemsHook` in `rubygems/lib/rubygems/rdoc.rb`,
documentations are not created with old RDoc.

Q3. When can we delete `rubygems/lib/rubygems/rdoc.rb`?

A.

We can delete it when all users use RDoc including `rubygems_plugin`.

Next ruby version is 3.4.
If it includes the RDoc including `rubygems_plugin`,
we can delete `rubygems/lib/rubygems/rdoc.rb` after ruby 3.3 is EOL.

Q4. Is it a breaking change that Rubygems creates documents with
rubygems_plugin not RDoc::RubygemsHook?

A.

No, it isn't.

If we simply implement this approach,
we move the implementation from `rdoc/lib/rdoc/rubygems_hook.rb` to
`rubygems_plugin.rb`.

This way can be breaking change.

It seems to be fine that we just need to delete `rdoc/rubygems_hook.rb` but it doesn't work.
It generates multiple documents.

`rubygems/lib/rubygems/rdoc.rb` has the following code.

```
begin
  require "rdoc/rubygems_hook"
  # ...
rescue LoadError
end
```

This code ignores RDoc related processes when `rdoc/rubygems_hook` can't be required.
But, this 'require' is not failed.

This is because Ruby installs Rdoc as a default gem.

So, Rdoc installed as a default gem generates documents and one installed as a normal gem does it too.

If you think that this behavior is accectable,
we can just delete `rdoc/rubygems_hook.rb`.

What do you think about this approach?

In this change, we take another approach to solve the problem that creates multiple documents.

If `Gem.done_installing(&Gem::RDoc.method(:generation_hook))` in `rubygems/rdoc.rb` doesn't create documents,
we can solve the problem.

We have some options.

* We change `rubygems/rdoc.rb` and then don't execute `Gem.done_installing`.
  (This is a change for RubyGems.)
* We change `rdoc/rubygems_hook.rb` and then make `generation_hook` a no-op method.
  (This is a change for RDoc.)

We choose the latter to avoid changing for RubyGems.

\### Test

\#### Preparation

Install Rdoc which including our changes by executing `rake install`.

❯ rake install

We confirmed that Rdoc which including our changes was installed.

❯ gem list | grep rdoc
rdoc (6.6.0, default: 6.4.0)

\#### Check point

We tested to check compatibility.

How to chack the compatibility?

We tested creating same documents by our RDoc and old RDoc with latest RubyGems.

We used following versions to test.

```
❯ ruby -v
ruby 3.1.0p0 (2021-12-25 revision fb4df44d16) [arm64-darwin22]

❯ gem list | grep rdoc
rdoc (default: 6.4.0)

❯ ruby -I rubygems/lib rubygems/exe/gem --version
3.5.14
```

Here is a result of test with old RDoc.
We can see that the document is created correctlly with `Parsing...` and `Done installing...`.

```
❯ ruby -I rubygems/lib rubygems/exe/gem install pkg-config
Successfully installed pkg-config-1.5.6
Parsing documentation for pkg-config-1.5.6
Done installing documentation for pkg-config after 0 seconds
1 gem installed
```

Here is a result of test with our RDoc.
We can see that the document is created correctlly with `Parsing...` and `Done installing...`.

```
❯ ruby -I rubygems/lib rubygems/exe/gem install pkg-config
Successfully installed pkg-config-1.5.6
Parsing documentation for pkg-config-1.5.6
Done installing documentation for pkg-config after 0 seconds
1 gem installed
```

As you can see we got the same results, our RDoc keeps compatibility.

* rename a test file

* Revert "rename a test file"

This reverts commit 70a144b.

* revert a test class name

* exclude `TestRDocRubyGemsHook` at job of ruby-core

* When `rubygems_plugin.rb` is not found, `test_rdoc_rubygems_hook.rb` is skipped.

* remove unnecessary whitespace

* add comment

* Add support for the case that RDoc is installed as a default gem

* Fix problems

Co-authored-by: mterada1228 <[email protected]>

* Simplify

* removed unused blank lines and revert test

* for rerun tests

* add comment for rubygems_plugin.rb

---------

Co-authored-by: Sutou Kouhei <[email protected]>
Co-authored-by: Sutou Kouhei <[email protected]>

lib/rdoc/rubygems_hook.rb

@@ -3,13 +3,19 @@
 require 'fileutils'
 require_relative '../rdoc'
 
-##
-# Gem::RDoc provides methods to generate RDoc and ri data for installed gems
-# upon gem installation.
+# We define the following two similar name classes in this file:
 #
-# This file is automatically required by RubyGems 1.9 and newer.
+# - RDoc::RubyGemsHook
+# - RDoc::RubygemsHook
+#
+# RDoc::RubyGemsHook is the main class that has real logic.
+#
+# RDoc::RubygemsHook is a class that is only for
+# compatibility. RDoc::RubygemsHook is used by RubyGems directly. We
+# can remove this when all maintained RubyGems remove
+# `rubygems/rdoc.rb`.
 
-class RDoc::RubygemsHook
+class RDoc::RubyGemsHook
 
   include Gem::UserInteraction
   extend  Gem::UserInteraction
@@ -45,7 +51,7 @@ class << self
   # Post installs hook that generates documentation for each specification in
   # +specs+
 
-  def self.generation_hook installer, specs
+  def self.generate installer, specs
     start = Time.now
     types = installer.document
 
@@ -64,6 +70,10 @@ def self.generation_hook installer, specs
     say "Done installing documentation for #{names} after #{duration} seconds"
   end
 
+  def self.remove uninstaller
+    new(uninstaller.spec).remove
+  end
+
   ##
   # Loads the RDoc generator
 
@@ -246,3 +256,43 @@ def setup
   end
 
 end
+
+# This class is referenced by RubyGems to create documents.
+# All implementations are moved to the above RubyGemsHook.
+#
+# This class does nothing when this RDoc is installed as a normal gem
+# or a bundled gem.
+#
+# This class does generate/remove documents for compatibility when
+# this RDoc is installed as a default gem.
+#
+# We can remove this when all maintained RubyGems remove
+# `rubygems/rdoc.rb`.
+module RDoc
+  class RubygemsHook
+    def self.default_gem?
+      !File.exist?(File.join(__dir__, "..", "rubygems_plugin.rb"))
+    end
+
+    def initialize(spec)
+      @spec = spec
+    end
+
+    def remove
+      # Do nothing if this is NOT a default gem.
+      return unless self.class.default_gem?
+
+      # Remove generated document for compatibility if this is a
+      # default gem.
+      RubyGemsHook.new(@spec).remove
+    end
+
+    def self.generation_hook installer, specs
+      # Do nothing if this is NOT a default gem.
+      return unless default_gem?
+
+      # Generate document for compatibility if this is a default gem.
+      RubyGemsHook.generate(installer, specs)
+    end
+  end
+end

lib/rubygems_plugin.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+# If this file is exist, RDoc generates and removes documents by rubygems plugins.
+#
+# In follwing cases,
+# RubyGems directly exectute RDoc::RubygemsHook.generation_hook and RDoc::RubygemsHook#remove to generate and remove documents.
+#
+# - RDoc is used as a default gem.
+# - RDoc is a old version that doesn't have rubygems_plugin.rb.
+
+require_relative 'rdoc/rubygems_hook'
+
+# To install dependency libraries of RDoc, you need to run bundle install.
+# At that time, rdoc/markdown is not generated.
+# If generate and remove are executed at that time, an error will occur.
+# So, we can't register generate and remove to Gem at that time.
+begin
+  require_relative 'rdoc/markdown'
+rescue LoadError
+else
+  Gem.done_installing(&RDoc::RubyGemsHook.method(:generate))
+  Gem.pre_uninstall(&RDoc::RubyGemsHook.method(:remove))
+end

test/rdoc/test_rdoc_rubygems_hook.rb

@@ -5,7 +5,7 @@
 require_relative '../../lib/rdoc/rubygems_hook'
 require 'test/unit'
 
-class TestRDocRubygemsHook < Test::Unit::TestCase
+class TestRDocRubyGemsHook < Test::Unit::TestCase
   def setup
     @a = Gem::Specification.new do |s|
       s.platform    = Gem::Platform::RUBY
@@ -40,10 +40,10 @@ def setup
     FileUtils.touch   File.join(@tempdir, 'a-2', 'lib', 'a.rb')
     FileUtils.touch   File.join(@tempdir, 'a-2', 'README')
 
-    @hook = RDoc::RubygemsHook.new @a
+    @hook = RDoc::RubyGemsHook.new @a
 
     begin
-      RDoc::RubygemsHook.load_rdoc
+      RDoc::RubyGemsHook.load_rdoc
     rescue Gem::DocumentError => e
       omit e.message
     end
@@ -63,7 +63,7 @@ def test_initialize
     refute @hook.generate_rdoc
     assert @hook.generate_ri
 
-    rdoc = RDoc::RubygemsHook.new @a, false, false
+    rdoc = RDoc::RubyGemsHook.new @a, false, false
 
     refute rdoc.generate_rdoc
     refute rdoc.generate_ri