Make it loose coupling between RubyGems and RDoc

Problems

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.

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.

Q2. 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.

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

A.

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.

The reason why the approach that just deletes `rdoc/rubygems.rb` creates multiple documents is `Gem.done_installing(&Gem::RDoc.method(:generation_hook))` in `rubygems/rdoc.rb`.

`rubygems/rdoc.rb` が Gem.done_installing しているところで ドキュメント生成がデフォルト gem によって行われているので、既存の Rubygems が require している RDoc::RubygemsHook は何も処理を実行しないようにしている。

↑ 次回:
- 動作確認について、手順、結果

Note

When RDoc and other gem were installed,
RubyGems plugin of RDoc wasn't executed.

For example

```
gem install rdoc pkg-config
```

Expected
	Installing RDoc creates a document of pkg-config.
Actual
	Installed RDoc creates a document of pkg-config.

See also.

ruby/rubygems#6673

| RDoc / rubyGems | New | Old |
| changed         |  A  |  A  |
| current         |  A  |  A  |

Because RDoc is default gem,

インストール済みの RDoc でドキュメント生成される。

ただし、この RDoc のバージョン以降を一度インストールすれば、
以降は Plugin によってドキュメント生成がされる。

旧バージョンとの違いは、
Plugin がドキュメント生成するかどうかの違いで、
アウトプットには違いがない。

=======

テスト結果の説明のために、
rdoc 未インストールの状態で、gem install rdoc pkg-config を実行してみる。
このパターンでは実行結果が Expect になるはず。

=> Ruby 3.x 以降で RDoc が default gem から bundled gem になる提案がある。
   将来の話、というテイでテストしておくのもあり？
=> 実際にテストしてみたところ、
   installing の rdoc で plugin を利用して document 生成がされた。

テスト方法

default gem がない状態を再現する方法

1. Move to a directory includes default gems.

$ cd $(ruby -e 'print RbConfig::CONFIG["rubylibdir"]')

2. Rename 'rdoc' and 'rdoc.rb'.

$ mv rdoc{,.bk}
$ mv rdoc.rb{,.bk}

3. Move to a directory includes specifications of default gems.

$ cd $(gem environment gemdir)/specifications/default

4. Rename 'rdoc-<versions>.gemspec'.

$ mv $(echo rdoc-*.gemspec){,.bk}

Author: mterada1228

lib/rdoc/rubygems_hook.rb

@@ -1,248 +1,17 @@
-# frozen_string_literal: true
-require 'rubygems/user_interaction'
-require 'fileutils'
-require_relative '../rdoc'
-
-##
-# Gem::RDoc provides methods to generate RDoc and ri data for installed gems
-# upon gem installation.
 #
-# This file is automatically required by RubyGems 1.9 and newer.
-
-class RDoc::RubygemsHook
-
-  include Gem::UserInteraction
-  extend  Gem::UserInteraction
-
-  @rdoc_version = nil
-  @specs = []
-
-  ##
-  # Force installation of documentation?
-
-  attr_accessor :force
-
-  ##
-  # Generate rdoc?
-
-  attr_accessor :generate_rdoc
-
-  ##
-  # Generate ri data?
-
-  attr_accessor :generate_ri
-
-  class << self
-
-    ##
-    # Loaded version of RDoc.  Set by ::load_rdoc
-
-    attr_reader :rdoc_version
-
-  end
-
-  ##
-  # Post installs hook that generates documentation for each specification in
-  # +specs+
-
-  def self.generation_hook installer, specs
-    start = Time.now
-    types = installer.document
-
-    generate_rdoc = types.include? 'rdoc'
-    generate_ri   = types.include? 'ri'
-
-    specs.each do |spec|
-      new(spec, generate_rdoc, generate_ri).generate
-    end
-
-    return unless generate_rdoc or generate_ri
-
-    duration = (Time.now - start).to_i
-    names    = specs.map(&:name).join ', '
-
-    say "Done installing documentation for #{names} after #{duration} seconds"
-  end
-
-  ##
-  # Loads the RDoc generator
-
-  def self.load_rdoc
-    return if @rdoc_version
-
-    require_relative 'rdoc'
-
-    @rdoc_version = Gem::Version.new ::RDoc::VERSION
-  end
-
-  ##
-  # Creates a new documentation generator for +spec+.  RDoc and ri data
-  # generation can be enabled or disabled through +generate_rdoc+ and
-  # +generate_ri+ respectively.
-  #
-  # Only +generate_ri+ is enabled by default.
-
-  def initialize spec, generate_rdoc = false, generate_ri = true
-    @doc_dir   = spec.doc_dir
-    @force     = false
-    @rdoc      = nil
-    @spec      = spec
-
-    @generate_rdoc = generate_rdoc
-    @generate_ri   = generate_ri
-
-    @rdoc_dir = spec.doc_dir 'rdoc'
-    @ri_dir   = spec.doc_dir 'ri'
-  end
-
-  ##
-  # Removes legacy rdoc arguments from +args+
-  #--
-  # TODO move to RDoc::Options
-
-  def delete_legacy_args args
-    args.delete '--inline-source'
-    args.delete '--promiscuous'
-    args.delete '-p'
-    args.delete '--one-file'
-  end
-
-  ##
-  # Generates documentation using the named +generator+ ("darkfish" or "ri")
-  # and following the given +options+.
-  #
-  # Documentation will be generated into +destination+
-
-  def document generator, options, destination
-    generator_name = generator
-
-    options = options.dup
-    options.exclude ||= [] # TODO maybe move to RDoc::Options#finish
-    options.setup_generator generator
-    options.op_dir = destination
-    Dir.chdir @spec.full_gem_path do
-      options.finish
-    end
-
-    generator = options.generator.new @rdoc.store, options
-
-    @rdoc.options = options
-    @rdoc.generator = generator
-
-    say "Installing #{generator_name} documentation for #{@spec.full_name}"
-
-    FileUtils.mkdir_p options.op_dir
-
-    Dir.chdir options.op_dir do
-      begin
-        @rdoc.class.current = @rdoc
-        @rdoc.generator.generate
-      ensure
-        @rdoc.class.current = nil
-      end
-    end
-  end
-
-  ##
-  # Generates RDoc and ri data
-
-  def generate
-    return if @spec.default_gem?
-    return unless @generate_ri or @generate_rdoc
-
-    setup
-
-    options = nil
-
-    args = @spec.rdoc_options
-    args.concat @spec.source_paths
-    args.concat @spec.extra_rdoc_files
-
-    case config_args = Gem.configuration[:rdoc]
-    when String then
-      args = args.concat config_args.split(' ')
-    when Array then
-      args = args.concat config_args
-    end
-
-    delete_legacy_args args
-
-    Dir.chdir @spec.full_gem_path do
-      options = ::RDoc::Options.new
-      options.default_title = "#{@spec.full_name} Documentation"
-      options.parse args
-    end
-
-    options.quiet = !Gem.configuration.really_verbose
-
-    @rdoc = new_rdoc
-    @rdoc.options = options
-
-    store = RDoc::Store.new
-    store.encoding = options.encoding
-    store.dry_run  = options.dry_run
-    store.main     = options.main_page
-    store.title    = options.title
-
-    @rdoc.store = store
-
-    say "Parsing documentation for #{@spec.full_name}"
-
-    Dir.chdir @spec.full_gem_path do
-      @rdoc.parse_files options.files
-    end
-
-    document 'ri',       options, @ri_dir if
-      @generate_ri   and (@force or not File.exist? @ri_dir)
-
-    document 'darkfish', options, @rdoc_dir if
-      @generate_rdoc and (@force or not File.exist? @rdoc_dir)
-  end
-
-  ##
-  # #new_rdoc creates a new RDoc instance.  This method is provided only to
-  # make testing easier.
-
-  def new_rdoc # :nodoc:
-    ::RDoc::RDoc.new
-  end
-
-  ##
-  # Is rdoc documentation installed?
-
-  def rdoc_installed?
-    File.exist? @rdoc_dir
-  end
-
-  ##
-  # Removes generated RDoc and ri data
-
-  def remove
-    base_dir = @spec.base_dir
-
-    raise Gem::FilePermissionError, base_dir unless File.writable? base_dir
-
-    FileUtils.rm_rf @rdoc_dir
-    FileUtils.rm_rf @ri_dir
-  end
-
-  ##
-  # Is ri data installed?
-
-  def ri_installed?
-    File.exist? @ri_dir
-  end
-
-  ##
-  # Prepares the spec for documentation generation
-
-  def setup
-    self.class.load_rdoc
+# This class is referenced by RubyGems to create documents.
+# Now, methods are moved to rubygems_plugin.rb.
+#
+# When old version RDoc is not used,
+# this class is not used from RubyGems too.
+# Then, remove this class.
+#
+module RDoc
+  class RubygemsHook
+    def initialize(spec); end
 
-    raise Gem::FilePermissionError, @doc_dir if
-      File.exist?(@doc_dir) and not File.writable?(@doc_dir)
+    def remove; end
 
-    FileUtils.mkdir_p @doc_dir unless File.exist? @doc_dir
+    def self.generation_hook installer, specs; end
   end
-
 end