rdoc-markdown 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 35702d5815f56256651a8994111e772ee761a19a0df97052816431c15247b73b
-  data.tar.gz: 3720a080b24825ea96ea487d5b264dcbe2cf2f4c5e8ea25be677e9c54a0b0f4e
+  metadata.gz: 56a6f33ad7581c2e300d358c58f4537c6154d064495600ea9bd1270116408073
+  data.tar.gz: 1a72d5f06233b6264138f9452a494cdada10e99dad50104c4c73473e450e347b
 SHA512:
-  metadata.gz: de2608fb5a61247ef9fd33153a8ab75bbfb21b9e3200078a1d59237340a0511cbee0866e90dce2d4a6d73408aed16bd2bb53e09f3e78118c083dd388b411c366
-  data.tar.gz: d5c8e5de4664c1300b8997c13948b296bd2ed39768396f5a5928cfea176f91130b51359f8ee982e24f2ef2a5284b10f53c2c4dbb6249d0e3726f9225a0e1212c
+  metadata.gz: 2abde2f7a06a945237f594f4bdb32c7103c51f7c3779b57e754f9cb58cca0c88252984547908ed6e201f3caacdf9e56e2d438602b8f6eee7beb8135754d4e563
+  data.tar.gz: a37cc849f3844ba85037b866939b0d3f1000293fa2c7c693745f99ba654244a4cbb1610fc8c0c804413a202a2a25d367dfd8954bb2178f03eb089560862783e9

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    rdoc-markdown (0.8.0)
+    rdoc-markdown (0.9.0)
       csv
       erb
       rdoc
@@ -112,6 +112,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
@@ -193,6 +197,7 @@ DEPENDENCIES
   mutant-minitest
   mutex_m
   rake (~> 13.0)
+  rbs
   rdiscount (~> 2.0)
   rdoc-markdown!
   simplecov (~> 0.22)

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

@@ -0,0 +1,78 @@
+# 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.
+  #
+  # @return [RDoc::Generator::Markdown::RbsSignatureIndex] Signature index.
+  def self.build(files)
+    rbs_files = files.select { |file| File.extname(file) == ".rbs" }
+    new(signatures_from(rbs_files))
+  end
+
+  # Builds signatures by reusing RBS's own RDoc parser.
+  #
+  # @param files [Array<String>] RBS files to parse.
+  #
+  # @return [Hash{Array => String}] Signature lookup keyed by class and method.
+  def self.signatures_from(files)
+    files.each_with_object({}) do |file, signatures|
+      parsed_classes(file).each do |klass|
+        klass.method_list.each do |method|
+          add_method_signature(signatures, klass: klass, method: method)
+        end
+      end
+    end
+  end
+
+  # Parses one RBS file into RDoc class/module objects.
+  #
+  # @param file [String] RBS file path.
+  #
+  # @return [Array<RDoc::Context>] Classes and modules parsed from RBS.
+  def self.parsed_classes(file)
+    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)
+    parser.scan
+    store.all_classes_and_modules
+  end
+
+  # Adds one RBS-parsed method signature to the lookup.
+  #
+  # @param signatures [Hash{Array => String}] Signature lookup being populated.
+  # @param klass [RDoc::Context] Method owner.
+  # @param method [RDoc::AnyMethod] Method parsed by the RBS plugin.
+  #
+  # @return [void]
+  def self.add_method_signature(signatures, klass:, method:)
+    signatures[[klass.full_name, method.singleton, method.name]] = method.param_seq
+
+    return unless method.name == "initialize" && !method.singleton
+
+    signatures[[klass.full_name, true, "new"]] = method.param_seq
+  end
+
+  # @param signatures [Hash{Array => String}] Signature lookup.
+  def initialize(signatures)
+    @signatures = signatures
+  end
+
+  # Looks up the RBS signature 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]]
+  end
+
+  # Checks whether any RBS signatures were parsed.
+  #
+  # @return [Boolean] True when type signatures are available.
+  def any?
+    @signatures.any?
+  end
+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,7 +386,7 @@ class RDoc::Generator::Markdown
   #
   # @return [String] Normalized method signature.
   def method_signature(method)
-    signature = method.param_seq
+    signature = @rbs_method_signatures.signature_for(method) || method.param_seq
     return "()" unless signature.match?(/\S/)
 
     signature = signature.gsub("->", " -> ")
@@ -393,6 +395,13 @@ class RDoc::Generator::Markdown
     merge_method_signature_arguments(signature, method.params)
   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.
   #
   # @param signature [String] Method signature from RDoc call sequence.
@@ -813,6 +822,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))
 
     @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.9.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.9.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
@@ -206,6 +220,7 @@ files:
 - 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