Support RDoc 8 formatter initialization (#2109)

* Support RDoc 8 formatter initialization

Preserve positional options for RDoc 4–7 and use the keyword-based formatter defaults for RDoc 8. Add regression coverage and test RDoc 7.2 and 8.x in CI.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 04620c2c-d05c-4684-9275-33956737b425

* Allow RDoc 8 in runtime dependency

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 93ffdf64-9ffd-47b4-b3d4-96dda4ae722d

* Apply suggestions from code review

* Replace stubbed RDoc tests with version-gated tests

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 93ffdf64-9ffd-47b4-b3d4-96dda4ae722d

* Update test/coverage_test.rb

* Use a single RDoc rendering test

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 93ffdf64-9ffd-47b4-b3d4-96dda4ae722d

* Test RDoc 8 on a single Ruby version

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 93ffdf64-9ffd-47b4-b3d4-96dda4ae722d

* Rely on existing RDoc fixture test

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 93ffdf64-9ffd-47b4-b3d4-96dda4ae722d

---------

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 04620c2c-d05c-4684-9275-33956737b425
Copilot-Session: 93ffdf64-9ffd-47b4-b3d4-96dda4ae722d

Author: joelhawksley

.github/workflows/ci.yml

@@ -9,14 +9,21 @@ permissions:
 
 jobs:
   build:
-    name: "Test / Ruby ${{ matrix.ruby }}"
+    name: "Test / Ruby ${{ matrix.ruby }} / RDoc ${{ matrix.rdoc }}"
     runs-on: ubuntu-latest
+    env:
+      RDOC_VERSION: "~> ${{ matrix.rdoc }}"
     strategy:
       matrix:
+        rdoc:
+          - "7.2.0"
         ruby:
           - "3.3"
           - "3.4"
           - "4.0"
+        include:
+          - ruby: "4.0"
+            rdoc: "8.0"
       fail-fast: false
 
     steps:
@@ -28,7 +35,11 @@ jobs:
       - uses: ruby/setup-ruby@a0102e0972be65f351c307e2d64b9314a57c8073 # v1
         with:
           ruby-version: ${{ matrix.ruby }}
-          bundler-cache: true
+          bundler-cache: ${{ matrix.rdoc == '7.2.0' }}
+
+      - name: Install RDoc 8 dependencies
+        if: matrix.rdoc == '8.0'
+        run: bundle update rdoc
 
       - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:

CONTRIBUTING.md

@@ -37,6 +37,11 @@ To run the tests:
 
 If nothing complains, congratulations!
 
+CI tests RDoc 7.2 and 8.x. To test RDoc 8.x locally:
+
+    $ RDOC_VERSION='~> 8.0' bundle update rdoc
+    $ RDOC_VERSION='~> 8.0' bundle exec rake
+
 ## Releasing a new version
 
 If you are the current maintainer of this gem:

Gemfile

@@ -5,7 +5,7 @@ gem "redcarpet", :platforms => :ruby
 gem "kramdown", :platforms => :jruby
 gem "RedCloth"
 gem "commonmarker", "~> 2.8.2"
-gem "rdoc", "~> 7.2.0"
+gem "rdoc", ENV.fetch("RDOC_VERSION", "~> 7.2.0")
 gem "org-ruby", "0.9.12"
 gem "creole", "~>0.5.0"
 gem "wikicloth", "=0.8.3"

Gemfile.lock

@@ -2,7 +2,7 @@ PATH
   remote: .
   specs:
     github-markup (6.0.0)
-      rdoc (< 8)
+      rdoc (< 9)
 
 GEM
   remote: https://rubygems.org/

README.md

@@ -21,7 +21,7 @@ you wish to run the library. You can also run `script/bootstrap` to fetch them a
 
 * [.markdown, .mdown, .mkdn, .md](http://daringfireball.net/projects/markdown/) -- `gem install commonmarker` (https://github.com/gjtorikian/commonmarker)
 * [.textile](https://textile-lang.com/) -- `gem install RedCloth` (https://github.com/jgarber/redcloth)
-* [.rdoc](https://ruby.github.io/rdoc/) -- `gem install rdoc -v 3.6.1`
+* [.rdoc](https://ruby.github.io/rdoc/) -- `gem install rdoc`
 * [.org](http://orgmode.org/) -- `gem install org-ruby` (https://github.com/wallyqs/org-ruby)
 * [.creole](http://wikicreole.org/) -- `gem install creole` (https://github.com/larsch/creole)
 * [.mediawiki, .wiki](http://www.mediawiki.org/wiki/Help:Formatting) -- `gem install wikicloth` (https://github.com/nricciar/wikicloth)

github-markup.gemspec

@@ -23,7 +23,7 @@ Gem::Specification.new do |s|
   s.test_files    = s.files.grep(%r{^(test|spec|features)/})
   s.require_paths = %w[lib]
 
-  s.add_dependency 'rdoc', '< 8'
+  s.add_dependency 'rdoc', '< 9'
 
   s.add_development_dependency 'rake', '~> 13'
   s.add_development_dependency 'activesupport', '~> 8.1.3'

lib/github/markup/rdoc.rb

@@ -10,13 +10,15 @@ def initialize
       end
 
       def render(filename, content, options: {})
-        if ::RDoc::VERSION.to_i >= 4
+        # RDoc 4-7 require positional Options; RDoc 8 uses keyword options.
+        # Each run covers only the installed RDoc's branch; CI tests both.
+        # :nocov:
+        if (4...8).cover?(::RDoc::VERSION.to_i)
           h = ::RDoc::Markup::ToHtml.new(::RDoc::Options.new)
         else
-          # :nocov: RDoc < 4 has been unsupported since Ruby 2.4 (2016); modern RDoc requires Options.
           h = ::RDoc::Markup::ToHtml.new
-          # :nocov:
         end
+        # :nocov:
         h.convert(content)
       end
 

test/coverage_test.rb

@@ -94,11 +94,6 @@ def test_try_require_returns_false_for_missing_gem
     refute md.send(:try_require, "github_markup_definitely_not_a_real_gem_#{Time.now.to_i}")
   end
 
-  # --- rdoc.rb legacy version branch --------------------------------------
-  # The `RDoc::VERSION < 4` branch in rdoc.rb is marked :nocov: in source
-  # because the modern RDoc::Markup::ToHtml constructor requires Options
-  # and the legacy zero-arg form has been broken since RDoc 4 (2013).
-
   # --- implementation.rb default render and Linguist-less match? ---------
 
   def test_base_implementation_render_raises_not_implemented_error