Support RDoc 8 formatter initialization

.github/workflows/ci.yml

@@ -9,10 +9,15 @@ 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"
+          - "8.0"
         ruby:
           - "3.3"
           - "3.4"
@@ -28,7 +33,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,10 +94,20 @@ 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).
+  # --- rdoc.rb formatter constructor compatibility -----------------------
+  # Only the tests matching the installed RDoc are defined; CI runs both.
+
+  if ::RDoc::VERSION.to_i >= 8
+    def test_rdoc_8_formatter_rejects_positional_options
+      assert_raises(ArgumentError) { ::RDoc::Markup::ToHtml.new(::RDoc::Options.new) }
+      assert_includes GitHub::Markup::RDoc.new.render("README.rdoc", "*bold*"), "<strong>bold</strong>"
+    end
+  else
+    def test_rdoc_7_formatter_requires_positional_options
+      assert_raises(ArgumentError) { ::RDoc::Markup::ToHtml.new }
+      assert_includes GitHub::Markup::RDoc.new.render("README.rdoc", "*bold*"), "<strong>bold</strong>"
+    end
+  end
 
   # --- implementation.rb default render and Linguist-less match? ---------
 

test/markup_test.rb

@@ -107,6 +107,23 @@ def test_rendering_by_symbol
     assert_match result, GitHub::Markup.render_s(GitHub::Markups::MARKUP_ASCIIDOC, markup).split.join
   end
 
+  def test_rdoc_rendering_by_filename_and_symbol
+    source = "= Title\n\nA *bold* paragraph.\n\n* One\n* Two\n"
+    results = [
+      GitHub::Markup.render("README.rdoc", source),
+      GitHub::Markup.render_s(GitHub::Markups::MARKUP_RDOC, source),
+    ]
+
+    results.each do |result|
+      document = Nokogiri::HTML.fragment(result)
+      document.css("h1 > span").remove
+      assert_equal "Title", document.at_css("h1").text
+      assert_equal "bold", document.at_css("p strong").text
+      assert_equal ["One", "Two"], document.css("ul li").map { |item| item.text.strip }
+    end
+    assert_equal results.first, results.last
+  end
+
   def test_raises_error_if_command_exits_non_zero
     GitHub::Markup.command(:doesntmatter, 'test/fixtures/fail.sh', /fail/, ['Java'], 'fail')
     assert GitHub::Markup.can_render?('README.java', 'stop swallowing errors')