From ea4e17e54e5f919ebcc8b36a7db223ba5e199b8b Mon Sep 17 00:00:00 2001 From: Joel Hawksley Date: Thu, 15 Oct 2026 09:51:51 -0600 Subject: [PATCH 1/8] Support RDoc 8 formatter initialization MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- .github/workflows/ci.yml | 13 +++++++++++-- CONTRIBUTING.md | 5 +++++ Gemfile | 2 +- README.md | 2 +- lib/github/markup/rdoc.rb | 5 ++--- test/coverage_test.rb | 38 ++++++++++++++++++++++++++++++++++---- test/markup_test.rb | 17 +++++++++++++++++ 7 files changed, 71 insertions(+), 11 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 9a3e5674..0223172b 100644 --- a/.github/workflows/ci.yml +++ b/.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: diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2c83e31e..9e2b9886 100644 --- a/CONTRIBUTING.md +++ b/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: diff --git a/Gemfile b/Gemfile index 6bb9fcb8..c111f6f1 100644 --- a/Gemfile +++ b/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" diff --git a/README.md b/README.md index 12188dcb..07f39b47 100644 --- a/README.md +++ b/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` (including RDoc 8.x) * [.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) diff --git a/lib/github/markup/rdoc.rb b/lib/github/markup/rdoc.rb index 3ac25151..e013ae6c 100644 --- a/lib/github/markup/rdoc.rb +++ b/lib/github/markup/rdoc.rb @@ -10,12 +10,11 @@ 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. + 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 h.convert(content) end diff --git a/test/coverage_test.rb b/test/coverage_test.rb index f5043b5d..403dc143 100644 --- a/test/coverage_test.rb +++ b/test/coverage_test.rb @@ -94,10 +94,40 @@ 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 ----------------------- + + def test_rdoc_4_through_7_receive_options + formatter = Class.new do + def initialize(options) + raise ArgumentError, "expected RDoc::Options" unless options.is_a?(::RDoc::Options) + end + + def convert(content); "rendered:#{content}"; end + end + + ["4.0.0", "6.3.4.1", "7.2.0"].each do |version| + with_stub_const("RDoc::VERSION", version) do + with_stub_const("RDoc::Markup::ToHtml", formatter) do + assert_equal "rendered:hello", GitHub::Markup::RDoc.new.render("README.rdoc", "hello") + end + end + end + end + + def test_rdoc_8_and_legacy_versions_receive_no_positional_options + formatter = Class.new do + def initialize; end + def convert(content); "rendered:#{content}"; end + end + + ["3.6.1", "8.0.0", "8.1.0"].each do |version| + with_stub_const("RDoc::VERSION", version) do + with_stub_const("RDoc::Markup::ToHtml", formatter) do + assert_equal "rendered:hello", GitHub::Markup::RDoc.new.render("README.rdoc", "hello") + end + end + end + end # --- implementation.rb default render and Linguist-less match? --------- diff --git a/test/markup_test.rb b/test/markup_test.rb index baa1dec2..e1426930 100644 --- a/test/markup_test.rb +++ b/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') From 30f50d6e46d7735119b84c5e01e68d6f05f6351f Mon Sep 17 00:00:00 2001 From: Joel Hawksley Date: Thu, 15 Oct 2026 12:05:45 -0600 Subject: [PATCH 2/8] Allow RDoc 8 in runtime dependency Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 93ffdf64-9ffd-47b4-b3d4-96dda4ae722d --- Gemfile.lock | 2 +- github-markup.gemspec | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/Gemfile.lock b/Gemfile.lock index f255b9c3..77cc42a8 100644 --- a/Gemfile.lock +++ b/Gemfile.lock @@ -2,7 +2,7 @@ PATH remote: . specs: github-markup (6.0.0) - rdoc (< 8) + rdoc (< 9) GEM remote: https://rubygems.org/ diff --git a/github-markup.gemspec b/github-markup.gemspec index 19d55653..1e6bd6ea 100644 --- a/github-markup.gemspec +++ b/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' From 4c28d17aa220b84732ea1c27256059427a5b5bbb Mon Sep 17 00:00:00 2001 From: Joel Hawksley Date: Thu, 15 Oct 2026 12:09:01 -0600 Subject: [PATCH 3/8] Apply suggestions from code review --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 07f39b47..018f54cc 100644 --- a/README.md +++ b/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` (including RDoc 8.x) +* [.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) From ce0e4fe52935a68fbdc00d19ea9e3092be0eb38d Mon Sep 17 00:00:00 2001 From: Joel Hawksley Date: Thu, 15 Oct 2026 12:17:56 -0600 Subject: [PATCH 4/8] 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 --- lib/github/markup/rdoc.rb | 3 +++ test/coverage_test.rb | 38 +++++++++----------------------------- 2 files changed, 12 insertions(+), 29 deletions(-) diff --git a/lib/github/markup/rdoc.rb b/lib/github/markup/rdoc.rb index e013ae6c..e3258e74 100644 --- a/lib/github/markup/rdoc.rb +++ b/lib/github/markup/rdoc.rb @@ -11,11 +11,14 @@ def initialize def render(filename, content, options: {}) # 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 h = ::RDoc::Markup::ToHtml.new end + # :nocov: h.convert(content) end diff --git a/test/coverage_test.rb b/test/coverage_test.rb index 403dc143..b0d0d558 100644 --- a/test/coverage_test.rb +++ b/test/coverage_test.rb @@ -95,37 +95,17 @@ def test_try_require_returns_false_for_missing_gem end # --- rdoc.rb formatter constructor compatibility ----------------------- + # Only the tests matching the installed RDoc are defined; CI runs both. - def test_rdoc_4_through_7_receive_options - formatter = Class.new do - def initialize(options) - raise ArgumentError, "expected RDoc::Options" unless options.is_a?(::RDoc::Options) - end - - def convert(content); "rendered:#{content}"; end - end - - ["4.0.0", "6.3.4.1", "7.2.0"].each do |version| - with_stub_const("RDoc::VERSION", version) do - with_stub_const("RDoc::Markup::ToHtml", formatter) do - assert_equal "rendered:hello", GitHub::Markup::RDoc.new.render("README.rdoc", "hello") - end - end + 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*"), "bold" end - end - - def test_rdoc_8_and_legacy_versions_receive_no_positional_options - formatter = Class.new do - def initialize; end - def convert(content); "rendered:#{content}"; end - end - - ["3.6.1", "8.0.0", "8.1.0"].each do |version| - with_stub_const("RDoc::VERSION", version) do - with_stub_const("RDoc::Markup::ToHtml", formatter) do - assert_equal "rendered:hello", GitHub::Markup::RDoc.new.render("README.rdoc", "hello") - end - 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*"), "bold" end end From 9fe5087957093dcada21a369aa01103e219ec0e2 Mon Sep 17 00:00:00 2001 From: Joel Hawksley Date: Thu, 15 Oct 2026 12:19:42 -0600 Subject: [PATCH 5/8] Update test/coverage_test.rb --- test/coverage_test.rb | 3 --- 1 file changed, 3 deletions(-) diff --git a/test/coverage_test.rb b/test/coverage_test.rb index b0d0d558..87ebd660 100644 --- a/test/coverage_test.rb +++ b/test/coverage_test.rb @@ -94,9 +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 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) } From 4221bc1602165e1c5910604592f7389471835f33 Mon Sep 17 00:00:00 2001 From: Joel Hawksley Date: Thu, 15 Oct 2026 12:21:15 -0600 Subject: [PATCH 6/8] 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/coverage_test.rb | 12 ++---------- 1 file changed, 2 insertions(+), 10 deletions(-) diff --git a/test/coverage_test.rb b/test/coverage_test.rb index 87ebd660..6f14d464 100644 --- a/test/coverage_test.rb +++ b/test/coverage_test.rb @@ -94,16 +94,8 @@ 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 - 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*"), "bold" - 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*"), "bold" - end + def test_rdoc_renders_with_installed_version + assert_includes GitHub::Markup::RDoc.new.render("README.rdoc", "*bold*"), "bold" end # --- implementation.rb default render and Linguist-less match? --------- From e75a9d73be5e57fbb2c1d2f3676b6bb4033b7d1d Mon Sep 17 00:00:00 2001 From: Joel Hawksley Date: Thu, 15 Oct 2026 12:23:23 -0600 Subject: [PATCH 7/8] 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 --- .github/workflows/ci.yml | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 0223172b..a3b6ca10 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -17,11 +17,13 @@ jobs: matrix: rdoc: - "7.2.0" - - "8.0" ruby: - "3.3" - "3.4" - "4.0" + include: + - ruby: "4.0" + rdoc: "8.0" fail-fast: false steps: From d658d1dd27b5e6937336ac8add9bc0d7324b08b5 Mon Sep 17 00:00:00 2001 From: Joel Hawksley Date: Thu, 15 Oct 2026 12:29:00 -0600 Subject: [PATCH 8/8] Rely on existing RDoc fixture test Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 93ffdf64-9ffd-47b4-b3d4-96dda4ae722d --- test/coverage_test.rb | 4 ---- test/markup_test.rb | 17 ----------------- 2 files changed, 21 deletions(-) diff --git a/test/coverage_test.rb b/test/coverage_test.rb index 6f14d464..c971d67d 100644 --- a/test/coverage_test.rb +++ b/test/coverage_test.rb @@ -94,10 +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 - def test_rdoc_renders_with_installed_version - assert_includes GitHub::Markup::RDoc.new.render("README.rdoc", "*bold*"), "bold" - end - # --- implementation.rb default render and Linguist-less match? --------- def test_base_implementation_render_raises_not_implemented_error diff --git a/test/markup_test.rb b/test/markup_test.rb index e1426930..baa1dec2 100644 --- a/test/markup_test.rb +++ b/test/markup_test.rb @@ -107,23 +107,6 @@ 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')