rdoc-markdown 0.8.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 35702d5815f56256651a8994111e772ee761a19a0df97052816431c15247b73b
-  data.tar.gz: 3720a080b24825ea96ea487d5b264dcbe2cf2f4c5e8ea25be677e9c54a0b0f4e
+  metadata.gz: a3af6b5292a9333e8e0749195f1b799f80015a2b23bc7c8bd47068f315671d5c
+  data.tar.gz: 759122408198407ee3f300ee7effa75e4f7d02cf765a989f30db4ee1d79b4fa9
 SHA512:
-  metadata.gz: de2608fb5a61247ef9fd33153a8ab75bbfb21b9e3200078a1d59237340a0511cbee0866e90dce2d4a6d73408aed16bd2bb53e09f3e78118c083dd388b411c366
-  data.tar.gz: d5c8e5de4664c1300b8997c13948b296bd2ed39768396f5a5928cfea176f91130b51359f8ee982e24f2ef2a5284b10f53c2c4dbb6249d0e3726f9225a0e1212c
+  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.8.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)
@@ -112,6 +116,10 @@ GEM
       nokogiri (>= 1.15.7, != 1.16.7, != 1.16.6, != 1.16.5, != 1.16.4, != 1.16.3, != 1.16.2, != 1.16.1, != 1.16.0.rc1, != 1.16.0)
     rainbow (3.1.1)
     rake (13.4.2)
+    rbs (4.0.2)
+      logger
+      prism (>= 1.6.0)
+      tsort
     rdiscount (2.2.7.4)
     rdoc (7.2.0)
       erb
@@ -163,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)
@@ -184,6 +193,7 @@ PLATFORMS
   x86_64-linux-gnu
 
 DEPENDENCIES
+  appraisal
   bundler (>= 2.0)
   commonmarker
   erb_lint
@@ -193,6 +203,7 @@ DEPENDENCIES
   mutant-minitest
   mutex_m
   rake (~> 13.0)
+  rbs
   rdiscount (~> 2.0)
   rdoc-markdown!
   simplecov (~> 0.22)

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

@@ -0,0 +1,183 @@
+# 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
+
+  # @param signatures [Hash{Array => Array<String>}] Signature lookup.
+  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.rb

@@ -12,6 +12,8 @@ require "optparse"
 class RDoc::Generator::Markdown
   RDoc::RDoc.add_generator self
 
+  require_relative "markdown/rbs_signature_index"
+
   # Directory containing ERB templates.
   TEMPLATE_DIR = File.expand_path(File.join(File.dirname(__FILE__), "..", "..", "templates"))
 
@@ -384,13 +386,28 @@ class RDoc::Generator::Markdown
   #
   # @return [String] Normalized method signature.
   def method_signature(method)
-    signature = method.param_seq
-    return "()" unless signature.match?(/\S/)
+    signatures = @rbs_method_signatures.signature_lines_for(method)
+    signatures = [method.param_seq] if signatures.empty?
+
+    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
 
-    signature = signature.gsub("->", " -> ")
-    signature = signature.gsub(/\s+/, " ").strip
-    signature = " #{signature}" if signature.start_with?("->")
-    merge_method_signature_arguments(signature, method.params)
+    return "()" if signatures.empty?
+
+    signatures.join(" | ")
+  end
+
+  # Checks whether this documentation set has parsed RBS signatures.
+  #
+  # @return [Boolean] True when type signatures are available.
+  def types_available?
+    @rbs_method_signatures.any?
   end
 
   # Merges RDoc parameter names into a type-only signature.
@@ -813,6 +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), @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.8.0"
+    VERSION = "0.10.0"
   end
 end

data/lib/templates/classfile.md.erb

@@ -1,5 +1,9 @@
 # <%= klass.type.capitalize %> <%= display_name(klass) %>
 <%= anchor(klass.aref.strip) %>
+<%- if types_available? -%>
+
+_Type signatures available._
+<%- end -%>
 <%- class_description = describe(klass) -%>
 <%- unless class_description.empty? -%>
 

data/rdoc-markdown.gemspec

@@ -41,6 +41,7 @@ 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.8.0
+  version: 0.10.0
 platform: ruby
 authors:
 - Stanislav (Stas) Katkov
@@ -135,6 +135,20 @@ 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
@@ -178,6 +192,7 @@ files:
 - ".standard.yml"
 - ".yard-lint.yml"
 - AGENTS.md
+- Appraisals
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - Gemfile
@@ -202,10 +217,13 @@ 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/markdown/version.rb
 - lib/templates/classfile.md.erb
 - mutant.yml