rdoc-markdown 0.13.2 → 0.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f8d5874e33560a773358b53ee711bb485e0daecde88e51ca7dd95c54046bcede
-  data.tar.gz: 876f010a0efd3779ca28d93dd60567b100cc20e28e5aa9fc93446b07fb9be6fe
+  metadata.gz: 868f92bb775186af57b719c6aa821b0e69ba3cd27988ac3e3eb549c2e10600cb
+  data.tar.gz: 30fcdb498301cbdddf420b12792e53d2f9f427a30f9e16d5f67527dbf0137e6e
 SHA512:
-  metadata.gz: d3bbc5ee66dabe686f3c984a2aeffc251c77c6315646c475b45a2076d039100e034d2cc482c6d1070c8ed49dde3e12a82b2c2350bd90b51103730568ccbf611e
-  data.tar.gz: 9d7941c568619a5c149bc844519b90bbe9d25530714a386e4a275286a95226ef308dba5e2c30f6b25b78d989eb9d81270b5a4a4486823b315eb93277d67305c5
+  metadata.gz: 92914fc1b0e03ecb0fb09dd2fb1bca56c6222a27beb7c9eb63882a8644567ffa7de863ece0476d688fb91cefcc9b89fcc2949722299724ea90ea3bc768dc2d2d
+  data.tar.gz: 61672973b235fa35b149ff24ab9dc1fd22ccf2eb0d907bad436bde63f73c76ec1f116b143d009adb39d482c59529f2a69929f5786f2e6d48bb49b38ea7b8fc06

data/.erb_lint.yml

@@ -30,10 +30,6 @@ linters:
       - Lint/EmptyExpression
       - Lint/SelfAssignment
       - Security/Eval
-    rubocop_config:
-      AllCops:
-        TargetRubyVersion: 3.2
-        NewCops: enable
   SpaceAroundErbTag:
     enabled: true
   TrailingWhitespace:

data/AGENTS.md

@@ -39,10 +39,11 @@ the user.
 
 You are done when all of these are green and not reporting any issues:
 
-```
+```bash
 bundle exec rake test
-bundle exec mutant run
+# don't run again if fail-fast has already passed
+bundle exec mutant run --fail-fast --since origin/main
 bundle exec rake markdown:validate
 bundle exec yard-lint
-bundle exec erb:lint
+bundle exec rake erb:lint
 ```

data/CHANGELOG.md

@@ -1,7 +1,14 @@
 # Changelog
 
+
 ## Unreleased
 
+## 0.14.0
+
+- BREAKING: Removing RDoc 7 compatibility code. Support RDoc 8 only.
+- Remove extra spacing between method group headings and  content.
+- Reworked documentation cross-linking. Tests will fail, if cross-linked document can't be found.
+
 ## 0.13.2
 
 - Don't add emtpy line break instead of missing metadata

data/Gemfile

@@ -5,16 +5,9 @@ source "https://rubygems.org"
 # Specify your gem's dependencies in rdoc-markdown.gemspec
 gemspec
 
-gem "rake", "~> 13.0"
-
-gem "appraisal"
 gem "erb_lint", require: false
-gem "minitest", "~> 5.0"
 gem "standard"
 gem "yard-lint"
 
-if Gem::Version.new(RUBY_VERSION) >= Gem::Version.new("3.3")
-  gem "mutant"
-  gem "mutant-minitest"
-  gem "mutex_m"
-end
+gem "mutant"
+gem "mutant-minitest"

data/Gemfile.lock

@@ -1,10 +1,10 @@
 PATH
   remote: .
   specs:
-    rdoc-markdown (0.13.2)
+    rdoc-markdown (0.14.0)
       csv
       erb
-      rdoc
+      rdoc (>= 8.0)
       reverse_markdown
 
 GEM
@@ -29,10 +29,6 @@ GEM
       securerandom (>= 0.3)
       tzinfo (~> 2.0, >= 2.0.5)
       uri (>= 0.13.1)
-    appraisal (2.5.0)
-      bundler
-      rake
-      thor (>= 0.14.0)
     ast (2.4.3)
     base64 (0.3.0)
     better_html (2.2.0)
@@ -49,11 +45,10 @@ GEM
     connection_pool (3.0.2)
     crass (1.0.6)
     csv (3.3.5)
-    date (3.5.1)
     diff-lcs (2.0.0)
     docile (1.4.1)
     drb (2.2.3)
-    erb (6.0.4)
+    erb (6.0.6)
     erb_lint (0.9.0)
       activesupport
       better_html (>= 2.0.1)
@@ -103,9 +98,6 @@ GEM
       prettyprint
     prettyprint (0.2.0)
     prism (1.9.0)
-    psych (5.3.1)
-      date
-      stringio
     racc (1.8.1)
     rails-dom-testing (2.3.0)
       activesupport (>= 5.0.0)
@@ -121,9 +113,10 @@ GEM
       prism (>= 1.6.0)
       tsort
     rdiscount (2.2.7.4)
-    rdoc (7.2.0)
+    rdoc (8.0.0)
       erb
-      psych (>= 4.0.0)
+      prism (>= 1.6.0)
+      rbs (>= 4.0.0)
       tsort
     regexp_parser (2.12.0)
     reline (0.6.3)
@@ -170,8 +163,6 @@ GEM
     standard-performance (1.9.0)
       lint_roller (~> 1.1)
       rubocop-performance (~> 1.26.0)
-    stringio (3.2.0)
-    thor (1.5.0)
     tsort (0.2.0)
     tzinfo (2.0.6)
       concurrent-ruby (~> 1.0)
@@ -193,7 +184,6 @@ PLATFORMS
   x86_64-linux-gnu
 
 DEPENDENCIES
-  appraisal
   bundler (>= 2.0)
   commonmarker
   erb_lint
@@ -201,9 +191,7 @@ DEPENDENCIES
   minitest-strict (~> 1.0)
   mutant
   mutant-minitest
-  mutex_m
   rake (~> 13.0)
-  rbs
   rdiscount (~> 2.0)
   rdoc-markdown!
   simplecov (~> 0.22)

data/README.md

@@ -13,6 +13,8 @@ It's a pitty that rdoc can't output a proper markdown file. Somebody has to try
 
 ## Installation
 
+rdoc-markdown requires Ruby 3.3 or newer and RDoc 8 or newer.
+
 Install gem and add to application's Gemfile by executing:
 
     $ bundle add rdoc-markdown
@@ -40,7 +42,7 @@ rdoc-markdown uses `reverse_markdown` to convert RDoc's HTML fragments to Markdo
 rdoc --format=markdown --markdown-unknown-tags=raise
 ```
 
-Accepted values are `pass_through`, `drop`, `bypass`, and `raise`. The default is `pass_through`, which matches `reverse_markdown`'s default behavior.
+Accepted values are `pass_through`, `drop`, `bypass`, and `raise`. The default is `pass_through`.
 
 The same setting can be stored in RDoc's `.rdoc_options` file:
 
@@ -57,7 +59,6 @@ There are decent tools that offer search through structured plain-text files. Bu
 In my personal use-case, I use SQLite. All other databases seem to have a good support for CSV imports.
 
 ## Development
-Biggest issue is testing this locally, but that's not as hard to do these days.
 
 ```
 gem build rdoc-markdown.gemspec
@@ -78,8 +79,6 @@ Following command should run entire testsuit:
 ```
 rake test
 ```
-The test suite loads `minitest-strict`, so boolean and nil assertions only pass on exact `true`, `false`, and `nil` values.
-Testing is not excessive, just verifies that basic functionality is operational.
 
 To validate generated markdown against GitHub Flavored Markdown and check local links/anchors:
 
@@ -96,12 +95,6 @@ This task validates:
 - vendored rails docs (Active Support, Active Record, Action Pack, Railties slices).
 
 Validation artifacts are written to `tmp/markdown-validate/` inside this repository.
-To fail on every unresolved vendor local link/anchor, run with:
-
-```
-MARKDOWN_VALIDATE_STRICT_VENDOR=1 rake markdown:validate
-```
-
 This task is also executed in CI.
 
 To lint markdown ERB templates:
@@ -110,7 +103,7 @@ To lint markdown ERB templates:
 bundle exec rake erb:lint
 ```
 
-### Integration harness: minitest
+### Integration: minitest
 To run the integration harness against minitest (aligned with docs.seattlerb.org/minitest):
 
 ```
@@ -120,7 +113,7 @@ bundle exec rake test
 
 The harness validates markdown formatting quality, generated page files, class/module paths, and search index output.
 
-### Integration harness: rails
+### Integration: rails
 To run the rails harness (focused on Active Support + Active Record API docs with sdoc-like structure):
 
 ```

data/Rakefile

@@ -31,7 +31,6 @@ end
 namespace :markdown do
   desc "Validate generated markdown as GitHub Flavored Markdown"
   task :validate do
-    strict_vendor_links = ENV["MARKDOWN_VALIDATE_STRICT_VENDOR"] == "1"
     validation_root = File.expand_path("tmp/markdown-validate", __dir__)
     FileUtils.rm_rf(validation_root)
     FileUtils.mkdir_p(validation_root)
@@ -57,18 +56,14 @@ namespace :markdown do
       output: minitest_output,
       files: minitest_docs_files(minitest_root)
     )
-    minitest_validator = MarkdownValidator.new(minitest_output, strict_links: strict_vendor_links)
-    minitest_count = minitest_validator.validate!
+    minitest_count = MarkdownValidator.new(minitest_output).validate!
     puts "Validated #{minitest_count} markdown files in #{minitest_output}"
-    puts "Skipped #{minitest_validator.unresolved_links} unresolved local links in vendored minitest docs"
 
     Rake::Task["vendor:setup:jekyll_seo_tag"].invoke
     jekyll_seo_tag_output = File.join(validation_root, JEKYLL_SEO_TAG_NAME)
     generate_jekyll_seo_tag_docs(output: jekyll_seo_tag_output)
-    jekyll_seo_tag_validator = MarkdownValidator.new(jekyll_seo_tag_output, strict_links: strict_vendor_links)
-    jekyll_seo_tag_count = jekyll_seo_tag_validator.validate!
+    jekyll_seo_tag_count = MarkdownValidator.new(jekyll_seo_tag_output).validate!
     puts "Validated #{jekyll_seo_tag_count} markdown files in #{jekyll_seo_tag_output}"
-    puts "Skipped #{jekyll_seo_tag_validator.unresolved_links} unresolved local links in vendored jekyll-seo-tag docs"
 
     Rake::Task["vendor:setup:rails"].invoke
     rails_root = File.expand_path("vendor/rails", __dir__)
@@ -79,10 +74,8 @@ namespace :markdown do
       output: rails_output,
       files: rails_validation_files(rails_root)
     )
-    rails_validator = MarkdownValidator.new(rails_output, strict_links: strict_vendor_links)
-    rails_count = rails_validator.validate!
+    rails_count = MarkdownValidator.new(rails_output).validate!
     puts "Validated #{rails_count} markdown files in #{rails_output}"
-    puts "Skipped #{rails_validator.unresolved_links} unresolved local links in vendored rails docs"
 
     puts "Markdown validation artifacts written to #{validation_root}"
   end
@@ -181,15 +174,10 @@ def rails_validation_files(root)
   files.concat(Dir[File.join(root, "actionpack/lib/**/*.rb")])
   files.concat(Dir[File.join(root, "railties/lib/**/*.rb")])
 
-  [
-    "activerecord/README.rdoc",
-    "actionpack/README.rdoc",
-    "railties/README.rdoc",
-    "railties/RDOC_MAIN.md"
-  ].each do |relative_path|
-    file = File.join(root, relative_path)
-    files << file if File.file?(file)
-  end
+  files.concat(Dir[File.join(root, "{active*,action*,railties}/README.{rdoc,md,markdown}")])
+
+  main_page = File.join(root, "railties/RDOC_MAIN.md")
+  files << main_page if File.file?(main_page)
 
   files.uniq
 end

data/lib/rdoc/generator/markdown/crossref.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+# Prevents RDoc from linking to code objects omitted from Markdown output.
+module RDoc::Generator::Markdown::CrossrefExtension
+  # Cross-reference resolver scoped to this formatter instance.
+  attr_writer :markdown_cross_reference
+
+  # Object IDs emitted by the active Markdown generator.
+  attr_writer :markdown_output_object_ids
+
+  # Renders a cross-reference only when its owning object is emitted.
+  #
+  # @param name [String, nil] Cross-reference target.
+  # @param text [String] Visible link text.
+  # @param code [Boolean] Whether to format code objects as code.
+  # @param rdoc_ref [Boolean] Whether the target uses the rdoc-ref scheme.
+  #
+  # @return [String] HTML link or unlinked text.
+  def link(name, text, code = true, rdoc_ref: false)
+    return super unless @markdown_cross_reference
+
+    ref = @markdown_cross_reference.resolve(name) if name
+    return super unless RDoc::CodeObject === ref
+
+    context = ref
+    context = context.parent until RDoc::ClassModule === context || RDoc::TopLevel === context
+    return super if @markdown_output_object_ids.include?(context.object_id)
+
+    return text if RDoc::TopLevel === ref || !code
+
+    "<code>#{text}</code>"
+  end
+end

data/lib/rdoc/generator/markdown.rb

@@ -1,19 +1,16 @@
 # frozen_string_literal: true
 # shareable_constant_value: literal
 
-gem "rdoc"
-
 require "erb"
 require "reverse_markdown"
 require "csv"
 require "optparse"
-require_relative "markdown/rdoc_markdown_pre"
 
 # Generates Markdown output and a CSV search index from an RDoc store.
 class RDoc::Generator::Markdown
   RDoc::RDoc.add_generator self
 
-  require_relative "markdown/rbs_signature_index"
+  require_relative "markdown/crossref"
 
   # Supported reverse_markdown unknown-tag modes.
   MARKDOWN_UNKNOWN_TAGS = %i[pass_through drop bypass raise]
@@ -109,11 +106,6 @@ class RDoc::Generator::Markdown
   # @return [RDoc::Store]
   attr_reader :store
 
-  # Working directory captured when the generator is created.
-  #
-  # @return [Pathname]
-  attr_reader :base_dir
-
   # Classes and modules selected for output.
   #
   # @return [Array<RDoc::Context>, nil]
@@ -124,15 +116,6 @@ class RDoc::Generator::Markdown
   # @return [Array<RDoc::TopLevel>, nil]
   attr_reader :pages
 
-  # Required by RDoc's generator interface; markdown output has no class subdirectory.
-  #
-  # @return [nil]
-  def class_dir
-  end
-
-  # this alias is required for rdoc to work
-  alias_method :file_dir, :class_dir
-
   # Creates a generator for an RDoc store and options.
   #
   # @param store [RDoc::Store] Source documentation store.
@@ -142,7 +125,6 @@ class RDoc::Generator::Markdown
     @options = rdoc_options
     @markdown_unknown_tags = self.class.validate_markdown_unknown_tags(rdoc_options.markdown_unknown_tags)
 
-    @base_dir = Pathname.pwd
     @expanded_root = Pathname(@options.root.to_s).expand_path
   end
 
@@ -254,16 +236,9 @@ class RDoc::Generator::Markdown
     @classes.each do |klass|
       content = template.result(binding)
       output_path = output_path_for(klass)
-
-      ([output_path] | legacy_paths_for(klass)).each do |destination_path|
-        out_file = Pathname.new("#{output_dir}/#{destination_path}")
-        out_file.dirname.mkpath
-        File.write(out_file, finalize_markdown(
-          content,
-          canonical_output_path: output_path,
-          current_output_path: destination_path
-        ))
-      end
+      out_file = Pathname.new("#{output_dir}/#{output_path}")
+      out_file.dirname.mkpath
+      File.write(out_file, finalize_markdown(content, current_output_path: output_path))
     end
   end
 
@@ -275,10 +250,9 @@ class RDoc::Generator::Markdown
       out_file = Pathname.new("#{output_dir}/#{page_output_path(page)}")
       out_file.dirname.mkpath
 
-      content = markdownify(page.description)
+      content = markdownify(render_description(page))
       File.write(out_file, finalize_markdown(
         content,
-        canonical_output_path: page_output_path(page),
         current_output_path: page_output_path(page)
       ))
     end
@@ -346,15 +320,6 @@ class RDoc::Generator::Markdown
     class_doc_for(code_object).fetch(:output_path)
   end
 
-  # Returns compatibility paths that should mirror the canonical output.
-  #
-  # @param code_object [RDoc::Context] Class or module object.
-  #
-  # @return [Array<String>] Legacy Markdown paths.
-  def legacy_paths_for(code_object)
-    class_doc_for(code_object).fetch(:legacy_paths)
-  end
-
   # Renders a class or module reference, linking it when its documentation is emitted.
   #
   # @param target [RDoc::ClassModule, String] Resolved RDoc object or unresolved name.
@@ -391,28 +356,61 @@ class RDoc::Generator::Markdown
     # - bypass - Ignore the unknown tag but try to convert its content
     # - raise - Raise an error to let you know
 
-    md = ReverseMarkdown.convert(input, github_flavored: true, unknown_tags: @markdown_unknown_tags).dup
-
-    # Flatten headings whose visible text is wrapped in a self-link.
-    md.gsub!(/^(#+)\s\[([^\]]+)\]\((?:#[^)]+)\)$/) { "#{Regexp.last_match(1)} #{Regexp.last_match(2)}" }
+    fragment = Nokogiri::HTML.fragment(input)
 
-    # Replace .html to .md extension in all local markdown links.
-    md.gsub!(%r{\]\((?!https?://|mailto:|#)([^)]+?)\.html((?:[?#][^)]+)?)\)}i) do
-      "](#{Regexp.last_match(1)}.md#{Regexp.last_match(2)})"
+    fragment.css("pre").each do |pre|
+      language = pre["class"].to_s[/\A(?!highlight\z)[A-Za-z][A-Za-z0-9_+-]*\z/]
+      pre["class"] = "brush: #{language};" if language
+      pre.inner_html = pre.text
     end
 
-    # Turn site-root markdown links into relative links.
-    md.gsub!(%r{\]\(/([^)]+?\.md(?:[?#][^)]+)?)\)}) { "](#{Regexp.last_match(1)})" }
+    fragment.css("h1, h2, h3, h4, h5, h6").each do |heading|
+      link = heading.xpath("./a[starts-with(@href, '#') and string-length(@href) > 1]").find do |anchor|
+        anchor.text.match?(/\S/) &&
+          anchor.xpath("preceding-sibling::node()").none? { |sibling| sibling.text.match?(/\S/) }
+      end
+      next unless link
+
+      id = link["href"].delete_prefix("#")
+      link.replace(link.children)
+      next if id == RDoc::Text.to_anchor(heading.text)
+
+      heading.add_child(fragment.document.create_element("span", "class" => "legacy-anchor", "id" => id))
+    end
 
-    # Strip RDoc structural path segments from internal links.
-    md.gsub!(%r{\]\(((?:\.\./)*)files/([^)]+?\.md(?:[?#][^)]+)?)\)}) do
-      "](#{Regexp.last_match(1)}#{Regexp.last_match(2)})"
+    anchor_aliases = fragment.css("span.legacy-anchor[id]").map.with_index do |span, index|
+      token = "RDocMarkdownAnchor#{index}End"
+      id = span["id"]
+      span.replace(token)
+      [token, id]
     end
-    md.gsub!(%r{\]\(((?:\.\./)*)classes/([^)]+?\.md(?:[?#][^)]+)?)\)}) do
-      "](#{Regexp.last_match(1)}#{Regexp.last_match(2)})"
+
+    fragment.css("a").each do |link|
+      receiver = link.text
+      href = link["href"].to_s
+
+      if receiver.match?(/\A(?:[A-Z][A-Za-z0-9_]*(?:::[A-Z][A-Za-z0-9_]*)*|[a-z_][A-Za-z0-9_]*)\z/) &&
+          href.match?(/\A(?::.+|".+")\z/)
+        link.replace(fragment.document.create_element("code") { |code| code.content = "#{receiver}[#{href}]" })
+      elsif href.start_with?("www.")
+        link["href"] = "https://#{href}"
+      elsif !href.match?(/\A(?:https?:\/\/|mailto:|#)/i)
+        href = href.sub(/\.html(?=[?#]|\z)/i, ".md")
+        href = href.sub(%r{\A/(?=.+\.md(?:[?#]|\z))}, "")
+        href = href.sub(%r{\A((?:\.\./)*)(?:files|classes|modules)/(?=.+\.md(?:[?#]|\z))}, '\1')
+        link["href"] = href
+      end
     end
-    md.gsub!(%r{\]\(((?:\.\./)*)modules/([^)]+?\.md(?:[?#][^)]+)?)\)}) do
-      "](#{Regexp.last_match(1)}#{Regexp.last_match(2)})"
+
+    md = ReverseMarkdown.convert(
+      fragment,
+      github_flavored: true,
+      unknown_tags: @markdown_unknown_tags
+    ).dup
+    anchor_aliases.each do |token, id|
+      anchor = %(<a id="#{id}"></a>)
+      md.gsub!("#{token}\n\n#", "#{anchor}\n#")
+      md.gsub!(token, anchor)
     end
 
     normalize_definition_list_code_blocks(md).rstrip
@@ -430,6 +428,25 @@ class RDoc::Generator::Markdown
     %(<a id="#{id}"></a>)
   end
 
+  # Renders an RDoc description with links limited to emitted objects.
+  #
+  # @param code_object [RDoc::CodeObject, RDoc::Context::Section] Object whose description is rendered.
+  #
+  # @return [String, nil] HTML description, or nil for an empty section.
+  def render_description(code_object)
+    return if RDoc::Context::Section === code_object && code_object.comments.empty?
+
+    formatter = code_object.formatter
+    formatter.extend(CrossrefExtension)
+    begin
+      formatter.markdown_cross_reference = RDoc::CrossReference.new(formatter.context)
+      formatter.markdown_output_object_ids = @markdown_output_object_ids
+      code_object.description
+    ensure
+      formatter.markdown_cross_reference = nil
+    end
+  end
+
   # Renders an RDoc object's description as Markdown.
   #
   # @param code_object [RDoc::CodeObject] Object with an RDoc description.
@@ -438,7 +455,7 @@ class RDoc::Generator::Markdown
   #
   # @return [String] Rendered description or fallback text.
   def describe(code_object, fallback: nil, heading_level_offset: 0)
-    description = code_object.description
+    description = render_description(code_object)
     return fallback.to_s if description.empty?
 
     shift_headings(markdownify(description), heading_level_offset)
@@ -451,7 +468,7 @@ class RDoc::Generator::Markdown
   #
   # @return [String] Rendered section description.
   def section_description(section, heading_level_offset:)
-    shift_headings(markdownify(section.description), heading_level_offset)
+    shift_headings(markdownify(render_description(section)), heading_level_offset)
   end
 
   # Builds the visible method signature used in headings.
@@ -460,8 +477,7 @@ class RDoc::Generator::Markdown
   #
   # @return [String] Normalized method signature.
   def method_signature(method)
-    signatures = @rbs_method_signatures.signature_lines_for(method)
-    signatures = [method.param_seq] if signatures.empty?
+    signatures = method.type_signature_lines || @store.rbs_signature_for(method) || [method.param_seq]
 
     signatures = signatures.filter_map do |signature|
       next unless signature&.match?(/\S/)
@@ -617,17 +633,12 @@ class RDoc::Generator::Markdown
   # Applies final whitespace and link normalization before writing Markdown.
   #
   # @param content [String] Markdown content.
-  # @param canonical_output_path [String] Canonical output path used to resolve links.
   # @param current_output_path [String] Output path for the file being written.
   #
   # @return [String] Final Markdown ending with one newline.
-  def finalize_markdown(content, canonical_output_path:, current_output_path:)
+  def finalize_markdown(content, current_output_path:)
     output = content.lines.map(&:rstrip).join("\n")
-    output = normalize_internal_links(
-      output,
-      canonical_output_path: canonical_output_path,
-      current_output_path: current_output_path
-    )
+    output = normalize_internal_links(output, current_output_path: current_output_path)
     output = output.sub(/\n{3,}/, "\n\n")
     "#{output}\n"
   end
@@ -704,12 +715,10 @@ class RDoc::Generator::Markdown
   # Rewrites local Markdown links relative to the current output file.
   #
   # @param markdown [String] Markdown content.
-  # @param canonical_output_path [String] Canonical output path used to resolve links.
   # @param current_output_path [String] Output path for the file being written.
   #
   # @return [String] Markdown with normalized internal links.
-  def normalize_internal_links(markdown, canonical_output_path:, current_output_path:)
-    canonical_dir = Pathname.new(canonical_output_path).dirname
+  def normalize_internal_links(markdown, current_output_path:)
     current_dir = Pathname.new(current_output_path).dirname
 
     markdown.gsub(%r{\]\(([^)]+)\)}) do
@@ -717,7 +726,7 @@ class RDoc::Generator::Markdown
       path = target.sub(/[?#].*\z/, "")
       suffix = target[path.length..]
 
-      resolved = resolve_output_path(path, canonical_dir)
+      resolved = resolve_output_path(path, current_dir)
       rewritten = resolved ? Pathname.new(resolved).relative_path_from(current_dir) : path
       "](#{rewritten}#{suffix})"
     end
@@ -780,14 +789,12 @@ class RDoc::Generator::Markdown
     classes.select(&:display?).each do |klass|
       display_name = normalized_full_name(klass.full_name)
       output_path = turn_to_path(display_name)
-      legacy_path = turn_to_path(klass.full_name)
       score = class_content_score(klass)
 
       candidate = {
         klass: klass,
         display_name: display_name,
         output_path: output_path,
-        legacy_paths: [legacy_path],
         score: score
       }
 
@@ -796,12 +803,7 @@ class RDoc::Generator::Markdown
       if existing.nil?
         docs_by_name[display_name] = candidate
       elsif candidate.fetch(:score) > existing.fetch(:score)
-        if existing.fetch(:score).positive?
-          candidate[:legacy_paths] |= existing.fetch(:legacy_paths)
-        end
         docs_by_name[display_name] = candidate
-      elsif candidate.fetch(:score).positive?
-        existing[:legacy_paths] |= candidate.fetch(:legacy_paths)
       end
     end
 
@@ -892,13 +894,8 @@ class RDoc::Generator::Markdown
     @class_docs_by_name = @class_docs.to_h { |doc| [doc.fetch(:display_name), doc] }
     @classes = @class_docs.map { |doc| doc.fetch(:klass) }
     @pages = @store.all_files.select(&:text?).select(&:display?).sort_by(&:base_name)
-    @rbs_method_signatures = RbsSignatureIndex.build(Array(@options.files), @base_dir, @store)
-
-    @known_output_paths = Set.new
-    @class_docs.each do |doc|
-      @known_output_paths << doc.fetch(:output_path)
-      doc.fetch(:legacy_paths).each { |path| @known_output_paths << path }
-    end
+    @markdown_output_object_ids = (@classes + @pages).map(&:object_id)
+    @known_output_paths = @class_docs.map { |doc| doc.fetch(:output_path) }
     @pages.each { |page| @known_output_paths << page_output_path(page) }
 
     @root_path_segment = Pathname.new(@options.root || ".").basename

data/lib/rdoc/markdown/version.rb

@@ -5,6 +5,6 @@ module Rdoc
   # @private
   module Markdown
     # @private
-    VERSION = "0.13.2"
+    VERSION = "0.14.0"
   end
 end

data/lib/templates/classfile.md.erb

@@ -58,7 +58,6 @@
 
 ### <%= visibility.capitalize %> <%= type.capitalize %> Methods
 <% methods.each do |method| -%>
-
 #### `<%= method.name %><%= method_signature(method) %>`<%= anchor(method.aref) %>
 <%= method_description(method, current_class: klass) %>
 <% end -%>

data/mutant.yml

@@ -13,4 +13,3 @@ requires:
 matcher:
   subjects:
     - RDoc::Generator::Markdown*
-    - ReverseMarkdown::Converters::RDocMarkdownPre*

data/rdoc-markdown.gemspec

@@ -12,7 +12,7 @@ Gem::Specification.new do |spec|
   spec.summary = "RDoc plugin to generate markdown documentation  "
   spec.description = "RDoc plugin to generate markdown documentation and search index as sqlite database for entire content."
   spec.homepage = "https://poshtui.com"
-  spec.required_ruby_version = ">= 2.7.0"
+  spec.required_ruby_version = ">= 3.3.0"
 
   # spec.metadata["allowed_push_host"] = "TODO: Set to your gem server 'https://example.com'"
 
@@ -33,7 +33,7 @@ Gem::Specification.new do |spec|
 
   spec.add_dependency "csv"
   spec.add_dependency "erb"
-  spec.add_dependency "rdoc"
+  spec.add_dependency "rdoc", ">= 8.0"
   spec.add_dependency "reverse_markdown"
 
   spec.add_development_dependency "bundler", ">= 2.0"
@@ -41,7 +41,6 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "minitest", "~> 5.0"
   spec.add_development_dependency "minitest-strict", "~> 1.0"
   spec.add_development_dependency "rake", "~> 13.0"
-  spec.add_development_dependency "rbs"
   spec.add_development_dependency "rdiscount", "~> 2.0"
   spec.add_development_dependency "simplecov", "~> 0.22"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rdoc-markdown
 version: !ruby/object:Gem::Version
-  version: 0.13.2
+  version: 0.14.0
 platform: ruby
 authors:
 - Stanislav (Stas) Katkov
@@ -43,14 +43,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '8.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '8.0'
 - !ruby/object:Gem::Dependency
   name: reverse_markdown
   requirement: !ruby/object:Gem::Requirement
@@ -135,20 +135,6 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '13.0'
-- !ruby/object:Gem::Dependency
-  name: rbs
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
 - !ruby/object:Gem::Dependency
   name: rdiscount
   requirement: !ruby/object:Gem::Requirement
@@ -192,7 +178,6 @@ files:
 - ".standard.yml"
 - ".yard-lint.yml"
 - AGENTS.md
-- Appraisals
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - Gemfile
@@ -217,14 +202,10 @@ files:
 - example/jekyll-seo-tag/Liquid.md
 - example/jekyll-seo-tag/Liquid/Tag.md
 - example/jekyll-seo-tag/index.csv
-- gemfiles/rdoc_7.gemfile
-- gemfiles/rdoc_8.gemfile
-- gemfiles/rdoc_head.gemfile
 - lib/markdown.rb
 - lib/rdoc/discover.rb
 - lib/rdoc/generator/markdown.rb
-- lib/rdoc/generator/markdown/rbs_signature_index.rb
-- lib/rdoc/generator/markdown/rdoc_markdown_pre.rb
+- lib/rdoc/generator/markdown/crossref.rb
 - lib/rdoc/markdown/version.rb
 - lib/templates/classfile.md.erb
 - mutant.yml
@@ -244,7 +225,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.7.0
+      version: 3.3.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="

data/Appraisals

@@ -1,13 +0,0 @@
-# frozen_string_literal: true
-
-appraise "rdoc_7" do
-  gem "rdoc", "~> 7.0"
-end
-
-appraise "rdoc_8" do
-  gem "rdoc", "~> 8.0"
-end
-
-appraise "rdoc_head" do
-  gem "rdoc", git: "https://github.com/ruby/rdoc.git", branch: "master"
-end

data/gemfiles/rdoc_7.gemfile

@@ -1,20 +0,0 @@
-# This file was generated by Appraisal
-
-source "https://rubygems.org"
-
-gem "rake", "~> 13.0"
-gem "appraisal"
-gem "erb_lint", require: false
-gem "minitest", "~> 5.0"
-gem "standard"
-gem "yard-lint"
-
-if Gem::Version.new(RUBY_VERSION) >= Gem::Version.new("3.3")
-  gem "mutant"
-  gem "mutant-minitest"
-  gem "mutex_m"
-end
-
-gem "rdoc", "~> 7.0"
-
-gemspec path: "../"

data/gemfiles/rdoc_8.gemfile

@@ -1,20 +0,0 @@
-# This file was generated by Appraisal
-
-source "https://rubygems.org"
-
-gem "rake", "~> 13.0"
-gem "appraisal"
-gem "erb_lint", require: false
-gem "minitest", "~> 5.0"
-gem "standard"
-gem "yard-lint"
-
-if Gem::Version.new(RUBY_VERSION) >= Gem::Version.new("3.3")
-  gem "mutant"
-  gem "mutant-minitest"
-  gem "mutex_m"
-end
-
-gem "rdoc", "~> 8.0"
-
-gemspec path: "../"

data/gemfiles/rdoc_head.gemfile

@@ -1,20 +0,0 @@
-# This file was generated by Appraisal
-
-source "https://rubygems.org"
-
-gem "rake", "~> 13.0"
-gem "appraisal"
-gem "erb_lint", require: false
-gem "minitest", "~> 5.0"
-gem "standard"
-gem "yard-lint"
-
-if Gem::Version.new(RUBY_VERSION) >= Gem::Version.new("3.3")
-  gem "mutant"
-  gem "mutant-minitest"
-  gem "mutex_m"
-end
-
-gem "rdoc", git: "https://github.com/ruby/rdoc.git", branch: "master"
-
-gemspec path: "../"

data/lib/rdoc/generator/markdown/rbs_signature_index.rb

@@ -1,187 +0,0 @@
-# frozen_string_literal: true
-
-# Optional lookup of method signatures parsed from RBS files.
-class RDoc::Generator::Markdown::RbsSignatureIndex
-  # Builds a signature index from RBS files included in an RDoc run.
-  #
-  # @param files [Array<String>] Input files passed to RDoc.
-  # @param base_dir [String, Pathname, nil] Directory where RDoc started.
-  # @param store [RDoc::Store, nil] Store containing Ruby code objects and RDoc 8 sidecar signatures.
-  #
-  # @return [RDoc::Generator::Markdown::RbsSignatureIndex] Signature index.
-  def self.build(files, base_dir = nil, store = nil)
-    rbs_files = files.select { |file| File.extname(file) == ".rbs" }
-    new(signatures_from_store(store).merge(signatures_from(rbs_files, base_dir)))
-  end
-
-  # Builds signatures by reusing RBS's own RDoc parser.
-  #
-  # @param files [Array<String>] RBS files to parse.
-  # @param base_dir [String, Pathname, nil] Directory where RDoc started.
-  #
-  # @return [Hash{Array => Array<String>}] Signature lookup keyed by class and method.
-  def self.signatures_from(files, base_dir)
-    files.each_with_object({}) do |file, signatures|
-      parsed_classes(file, base_dir).each do |klass|
-        klass.method_list.each do |method|
-          add_method_signature_lines(signatures, klass: klass, method: method, lines: rbs_signature_lines_from_method(method))
-        end
-      end
-    end
-  end
-
-  # Builds signatures already merged into an RDoc store.
-  #
-  # @param store [RDoc::Store, nil] Store containing Ruby code objects and RDoc 8 sidecar signatures.
-  #
-  # @return [Hash{Array => Array<String>}] Signature lookup keyed by class and method.
-  def self.signatures_from_store(store)
-    return {} unless store
-
-    store.all_classes_and_modules.each_with_object({}) do |klass, signatures|
-      klass.method_list.each do |method|
-        add_method_signature_lines(signatures, klass: klass, method: method, lines: store_signature_lines_from_method(method, store))
-      end
-    end
-  end
-
-  # Parses one RBS file into RDoc class/module objects.
-  #
-  # @param file [String] RBS file path.
-  # @param base_dir [String, Pathname, nil] Directory where RDoc started.
-  #
-  # @return [Array<RDoc::Context>] Classes and modules parsed from RBS.
-  def self.parsed_classes(file, base_dir)
-    file_path = rbs_file_path(file, base_dir)
-    store = RDoc::Store.new(RDoc::Options.new)
-    top_level = store.add_file(file_path)
-    parser = RDoc::Parser.for(top_level, File.read(file_path), store.options, nil)
-    parser.scan
-    store.all_classes_and_modules
-  end
-
-  # Resolves an RBS file path against the directory RDoc started from.
-  # RDoc changes into the output directory before generators run.
-  #
-  # @param file [String] RBS file path passed to RDoc.
-  # @param base_dir [String, Pathname, nil] Directory where RDoc started.
-  #
-  # @return [String] Absolute or already absolute RBS file path.
-  def self.rbs_file_path(file, base_dir)
-    Pathname.new(file).expand_path(base_dir).to_s
-  end
-
-  # Adds resolved method signature lines to the lookup.
-  #
-  # @param signatures [Hash{Array => Array<String>}] Signature lookup being populated.
-  # @param klass [RDoc::Context] Method owner.
-  # @param method [RDoc::AnyMethod] Method object.
-  # @param lines [Array<String>] Signature text lines.
-  #
-  # @return [void]
-  def self.add_method_signature_lines(signatures, klass:, method:, lines:)
-    return if lines.empty?
-
-    signatures[[klass.full_name, method.singleton, method.name]] = lines
-
-    return unless method.name == "initialize" && !method.singleton
-
-    signatures[[klass.full_name, true, "new"]] = lines
-  end
-
-  # Extracts explicit RBS method signature lines from RDoc parser output.
-  # RDoc 7 exposes parsed RBS signatures through `param_seq`; RDoc 8 stores
-  # them as `type_signature_lines`.
-  #
-  # @param method [RDoc::AnyMethod] Method parsed by RDoc's RBS parser.
-  #
-  # @return [Array<String>] RBS signature lines.
-  def self.rbs_signature_lines_from_method(method)
-    lines = method_type_signature_lines(method)
-    lines = method.param_seq if lines.empty?
-    nonblank_lines(lines)
-  end
-
-  # Extracts RBS method signature lines already merged into a Ruby store.
-  # Unlike explicit RBS parser output, ordinary Ruby `param_seq` is not a type
-  # signature and must not populate the index.
-  #
-  # @param method [RDoc::AnyMethod] Method object from the Ruby store.
-  # @param store [RDoc::Store] Store with sidecar RBS signatures.
-  #
-  # @return [Array<String>] RBS signature lines.
-  def self.store_signature_lines_from_method(method, store)
-    lines = method_type_signature_lines(method)
-    lines = store_type_signature_lines(method, store) if lines.empty?
-    lines
-  end
-
-  # Extracts RDoc 8 inline type signatures from a method.
-  #
-  # @param method [RDoc::AnyMethod] Method object.
-  #
-  # @return [Array<String>] Signature lines.
-  def self.method_type_signature_lines(method)
-    return [] unless method.respond_to?(:type_signature_lines)
-
-    nonblank_lines(method.type_signature_lines)
-  end
-
-  # Extracts RDoc 8 sidecar signatures from a store.
-  #
-  # @param method [RDoc::AnyMethod] Method object.
-  # @param store [RDoc::Store, nil] Optional RDoc store with sidecar RBS signatures.
-  #
-  # @return [Array<String>] Signature lines.
-  def self.store_type_signature_lines(method, store)
-    return [] unless store.respond_to?(:rbs_signature_for)
-
-    nonblank_lines(store.rbs_signature_for(method))
-  end
-
-  # Normalizes a signature-line value to non-blank strings.
-  #
-  # @param lines [Array<String>, String, nil] Signature text lines.
-  #
-  # @return [Array<String>] Non-blank signature lines.
-  def self.nonblank_lines(lines)
-    Array(lines).select { |line| line&.match?(/\S/) }
-  end
-
-  # Creates an immutable signature index.
-  #
-  # @param signatures [Hash{Array => Array<String>}] Signature lookup.
-  #
-  # @return [void]
-  def initialize(signatures)
-    @signatures = signatures
-  end
-
-  # Looks up the RBS signature lines for an RDoc method.
-  #
-  # @param method [RDoc::AnyMethod] Method object to render.
-  #
-  # @return [Array<String>] RBS method type lines when available.
-  def signature_lines_for(method)
-    @signatures.fetch([method.parent.full_name, method.singleton, method.name], [])
-  end
-
-  # Checks whether any RBS signatures were parsed.
-  #
-  # @return [Boolean] True when type signatures are available.
-  def any?
-    @signatures.any?
-  end
-
-  private_class_method \
-    :signatures_from,
-    :signatures_from_store,
-    :parsed_classes,
-    :rbs_file_path,
-    :add_method_signature_lines,
-    :rbs_signature_lines_from_method,
-    :store_signature_lines_from_method,
-    :method_type_signature_lines,
-    :store_type_signature_lines,
-    :nonblank_lines
-end

data/lib/rdoc/generator/markdown/rdoc_markdown_pre.rb

@@ -1,40 +0,0 @@
-# frozen_string_literal: true
-
-# Preserves simple <pre class="ruby"> language metadata emitted by RDoc.
-class ReverseMarkdown::Converters::RDocMarkdownPre < ReverseMarkdown::Converters::Pre
-  # Matches RDoc's plain language class names on pre blocks.
-  LANGUAGE_CLASS = /\A(?!highlight\z)[A-Za-z][A-Za-z0-9_+-]*\z/
-
-  # Converts an RDoc pre block into a GitHub-flavored Markdown fence.
-  #
-  # @param node [Nokogiri::XML::Node] RDoc pre node.
-  # @param _state [Hash] reverse_markdown converter state.
-  #
-  # @return [String] Markdown code fence.
-  def convert(node, _state)
-    content = treat_children(rdoc_pre_node(node), {})
-    "\n```#{language(node)}\n" << content << "\n```\n"
-  end
-
-  private
-
-  # Rebuilds a plain pre node from RDoc-highlighted text.
-  #
-  # @param node [Nokogiri::XML::Node] RDoc pre node.
-  #
-  # @return [Nokogiri::XML::Node] Plain pre node.
-  def rdoc_pre_node(node)
-    Nokogiri::HTML.fragment("<pre>#{node.text}</pre>").at("pre")
-  end
-
-  # Extracts the Markdown fence language.
-  #
-  # @param node [Nokogiri::XML::Node] RDoc pre node.
-  #
-  # @return [String, nil] Language name, or nil when no language is known.
-  def language(node)
-    node["class"].to_s[LANGUAGE_CLASS] || super
-  end
-end
-
-ReverseMarkdown::Converters.register :pre, ReverseMarkdown::Converters::RDocMarkdownPre.new