rdoc-markdown 0.9.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 56a6f33ad7581c2e300d358c58f4537c6154d064495600ea9bd1270116408073
-  data.tar.gz: 1a72d5f06233b6264138f9452a494cdada10e99dad50104c4c73473e450e347b
+  metadata.gz: a3af6b5292a9333e8e0749195f1b799f80015a2b23bc7c8bd47068f315671d5c
+  data.tar.gz: 759122408198407ee3f300ee7effa75e4f7d02cf765a989f30db4ee1d79b4fa9
 SHA512:
-  metadata.gz: 2abde2f7a06a945237f594f4bdb32c7103c51f7c3779b57e754f9cb58cca0c88252984547908ed6e201f3caacdf9e56e2d438602b8f6eee7beb8135754d4e563
-  data.tar.gz: a37cc849f3844ba85037b866939b0d3f1000293fa2c7c693745f99ba654244a4cbb1610fc8c0c804413a202a2a25d367dfd8954bb2178f03eb089560862783e9
+  metadata.gz: e259a75c590f3414e036763c213a3b19e8df9d78a964155ba20ebb6b5ec440b25cca3b4a925fc39181100267079cd89e30db711aabb087b34245b72dc3ca9873
+  data.tar.gz: e70488f82388bdbb6e1bd8a99e32864da66c86adf2e8cf58f2ee3775523a9283002b30aa31f8a8d080cc70812d6efcee5300bffb665b4bf432b2fd8643db5a86

data/Appraisals

@@ -0,0 +1,13 @@
+# 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/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 ## Unreleased
 
+## 0.10.0
+
+- Reworked RDoc 8 support
+
+## 0.9.0
+
+### Fixed
+- Render RDoc 8 inline and sidecar RBS signatures in Markdown method headings.
+- Resolve explicit relative `.rbs` inputs against the directory where RDoc started, not the output directory.
+
+### Changed
+- Run CI against both RDoc 7 and RDoc 8 dependency sets.
+
 ## 0.8.0
 
 ### Added

data/Gemfile

@@ -7,6 +7,7 @@ gemspec
 
 gem "rake", "~> 13.0"
 
+gem "appraisal"
 gem "erb_lint", require: false
 gem "minitest", "~> 5.0"
 gem "standard"

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    rdoc-markdown (0.9.0)
+    rdoc-markdown (0.10.0)
       csv
       erb
       rdoc
@@ -29,6 +29,10 @@ 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)
@@ -167,6 +171,7 @@ GEM
       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)
@@ -188,6 +193,7 @@ PLATFORMS
   x86_64-linux-gnu
 
 DEPENDENCIES
+  appraisal
   bundler (>= 2.0)
   commonmarker
   erb_lint

data/Rakefile

@@ -21,7 +21,10 @@ task default: [:test]
 namespace :erb do
   desc "Lint markdown ERB templates"
   task :lint do
-    sh "bundle exec erb_lint --lint-all"
+    files = Dir["lib/templates/**/*.{md,markdown}.erb"]
+    raise "No markdown ERB templates found" if files.empty?
+
+    sh "bundle", "exec", "erb_lint", *files
   end
 end
 

data/gemfiles/rdoc_7.gemfile

@@ -0,0 +1,20 @@
+# 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

@@ -0,0 +1,20 @@
+# 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,5 +1,20 @@
-# frozen_string_literal: true
+# This file was generated by Appraisal
 
-eval_gemfile "../Gemfile"
+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

@@ -5,68 +5,161 @@ 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)
+  def self.build(files, base_dir = nil, store = nil)
     rbs_files = files.select { |file| File.extname(file) == ".rbs" }
-    new(signatures_from(rbs_files))
+    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 => String}] Signature lookup keyed by class and method.
-  def self.signatures_from(files)
+  # @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).each do |klass|
+      parsed_classes(file, base_dir).each do |klass|
         klass.method_list.each do |method|
-          add_method_signature(signatures, klass: klass, method: 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)
+  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)
-    parser = RDoc::Parser.for(top_level, File.read(file), store.options, nil)
+    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
 
-  # Adds one RBS-parsed method signature to the lookup.
+  # 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 => String}] Signature lookup being populated.
+  # @param signatures [Hash{Array => Array<String>}] Signature lookup being populated.
   # @param klass [RDoc::Context] Method owner.
-  # @param method [RDoc::AnyMethod] Method parsed by the RBS plugin.
+  # @param method [RDoc::AnyMethod] Method object.
+  # @param lines [Array<String>] Signature text lines.
   #
   # @return [void]
-  def self.add_method_signature(signatures, klass:, method:)
-    signatures[[klass.full_name, method.singleton, method.name]] = method.param_seq
+  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"]] = method.param_seq
+    signatures[[klass.full_name, true, "new"]] = lines
   end
 
-  # @param signatures [Hash{Array => String}] Signature lookup.
+  # 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
+
+  # @param signatures [Hash{Array => Array<String>}] Signature lookup.
   def initialize(signatures)
     @signatures = signatures
   end
 
-  # Looks up the RBS signature for an RDoc method.
+  # Looks up the RBS signature lines for an RDoc method.
   #
   # @param method [RDoc::AnyMethod] Method object to render.
   #
-  # @return [String, nil] RBS method type string when available.
-  def signature_for(method)
-    @signatures[[method.parent.full_name, method.singleton, method.name]]
+  # @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.
@@ -75,4 +168,16 @@ class RDoc::Generator::Markdown::RbsSignatureIndex
   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.rb

@@ -386,13 +386,21 @@ class RDoc::Generator::Markdown
   #
   # @return [String] Normalized method signature.
   def method_signature(method)
-    signature = @rbs_method_signatures.signature_for(method) || method.param_seq
-    return "()" unless signature.match?(/\S/)
+    signatures = @rbs_method_signatures.signature_lines_for(method)
+    signatures = [method.param_seq] if signatures.empty?
 
-    signature = signature.gsub("->", " -> ")
-    signature = signature.gsub(/\s+/, " ").strip
-    signature = " #{signature}" if signature.start_with?("->")
-    merge_method_signature_arguments(signature, method.params)
+    signatures = signatures.filter_map do |signature|
+      next unless signature&.match?(/\S/)
+
+      signature = signature.gsub("->", " -> ")
+      signature = signature.gsub(/\s+/, " ").strip
+      signature = " #{signature}" if signature.start_with?("->")
+      merge_method_signature_arguments(signature, method.params)
+    end
+
+    return "()" if signatures.empty?
+
+    signatures.join(" | ")
   end
 
   # Checks whether this documentation set has parsed RBS signatures.
@@ -822,7 +830,7 @@ class RDoc::Generator::Markdown
     @class_docs_by_object_id = @class_docs.to_h { |doc| [doc.fetch(:klass).object_id, 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))
+    @rbs_method_signatures = RbsSignatureIndex.build(Array(@options.files), @base_dir, @store)
 
     @known_output_paths = Set.new
     @class_docs.each do |doc|

data/lib/rdoc/markdown/version.rb

@@ -5,6 +5,6 @@ module Rdoc
   # Version namespace for rdoc-markdown.
   module Markdown
     # Current gem version.
-    VERSION = "0.9.0"
+    VERSION = "0.10.0"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rdoc-markdown
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 0.10.0
 platform: ruby
 authors:
 - Stanislav (Stas) Katkov
@@ -192,6 +192,7 @@ files:
 - ".standard.yml"
 - ".yard-lint.yml"
 - AGENTS.md
+- Appraisals
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - Gemfile
@@ -216,6 +217,8 @@ 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