rdoc-markdown 0.21.1 → 0.22.0

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

@@ -7,17 +7,6 @@ module RDoc::Generator::Markdown::Signatures
     "(" => ")", "[" => "]", "{" => "}"
   }.freeze
 
-  # Builds the visible method signature used in headings.
-  #
-  # @param method [RDoc::AnyMethod] Method object to render.
-  #
-  # @return [String] Complete signature including the method name or documented receiver.
-  def method_signature(method)
-    RDoc::Generator::Markdown::Signatures.render_method_signature(method, store)
-  end
-
-  private :method_signature
-
   # Builds a complete method heading signature from RDoc and store metadata.
   #
   # @param method [RDoc::AnyMethod] Method object to render.
@@ -25,8 +14,9 @@ module RDoc::Generator::Markdown::Signatures
   #
   # @return [String] Complete signature including the method name or documented receiver.
   def self.render_method_signature(method, store)
+    name = method.name
     signatures = method.type_signature_lines || store.rbs_signature_for(method)
-    if !signatures && (call_seq = bracket_call_sequence(method))
+    if !signatures && ["[]", "[]="].include?(name) && (call_seq = method.call_seq)
       return call_seq.lines.map { |line| normalize_signature(line) }.join(" | ")
     end
     signatures ||= [method.param_seq]
@@ -39,17 +29,7 @@ module RDoc::Generator::Markdown::Signatures
       merge_method_signature_arguments(signature, method.params)
     end
 
-    signature = signatures.empty? ? "()" : signatures.join(" | ")
-    "#{method.name}#{signature}"
-  end
-
-  # Returns the original call syntax for bracket operators, when documented.
-  #
-  # @param method [RDoc::AnyMethod] Method object to render.
-  #
-  # @return [String, nil] Documented bracket calls, or nil for other signatures.
-  def self.bracket_call_sequence(method)
-    method.call_seq if ["[]", "[]="].include?(method.name)
+    "#{name}#{signatures.empty? ? "()" : signatures.join(" | ")}"
   end
 
   # Normalizes spacing in a signature without changing its call syntax.
@@ -68,7 +48,8 @@ module RDoc::Generator::Markdown::Signatures
   #
   # @return [String] Signature with names added when safe.
   def self.merge_method_signature_arguments(signature, raw_params)
-    params = normalized_method_params(raw_params)
+    params = raw_params.to_s.strip
+    params = params[1...-1] if params.start_with?("(") && params.end_with?(")")
 
     signature_args, signature_suffix = split_signature_arguments_and_suffix(signature)
     return signature unless signature_args
@@ -77,21 +58,18 @@ module RDoc::Generator::Markdown::Signatures
     signature_parts = split_signature_list(signature_args)
     return signature unless param_parts.length.eql?(signature_parts.length)
 
-    merged = merged_signature(param_parts, signature_parts, signature_suffix)
-    merged || signature
+    merged_signature(param_parts, signature_parts, signature_suffix) || signature
   end
 
-  # Merges matching parameter and signature fragments.
-  #
+  # Merges matching parameter and type fragments only when names can be inferred.
   # @param param_parts [Array<String>] RDoc parameter fragments.
   # @param signature_parts [Array<String>] Signature type fragments.
   # @param signature_suffix [String] Text following the argument list.
-  #
   # @return [String, nil] Merged signature, or nil when merging is unsafe or unnecessary.
   def self.merged_signature(param_parts, signature_parts, signature_suffix)
-    param_names = param_parts.map { |part| extract_parameter_name(part) }
+    param_names = param_parts.map { |part| part[/\A(?:\*\*|\*|&)?([a-z_]\w*):?\z/, 1] }
     return if param_names.any?(&:nil?)
-    return if signature_parts.zip(param_names).all? { |part, name| signature_part_mentions_name?(part, name) }
+    return if signature_parts.zip(param_names).all? { |part, name| part.match?(/(?<!\w)#{name}(?!\w)/) }
 
     merged_args = param_parts.zip(signature_parts).map do |param, type|
       separator = param.end_with?(":") ? " " : ": "
@@ -101,18 +79,6 @@ module RDoc::Generator::Markdown::Signatures
     "(#{merged_args.join(", ")})#{signature_suffix}"
   end
 
-  # Normalizes RDoc's raw parameter string.
-  #
-  # @param raw_params [String, nil] Parameter list from RDoc.
-  #
-  # @return [String] Parameter list without outer parentheses.
-  def self.normalized_method_params(raw_params)
-    params = raw_params.to_s.strip
-    params = params[1...-1] if params.start_with?("(") && params.end_with?(")")
-
-    params
-  end
-
   # Splits a parenthesized signature into arguments and suffix.
   #
   # @param signature [String] Method signature.
@@ -144,7 +110,7 @@ module RDoc::Generator::Markdown::Signatures
     delimiters = []
 
     list.each_char do |char|
-      if top_level_signature_separator?(char, delimiters)
+      if char == "," && delimiters.empty?
         parts << current.strip
         current.clear
       else
@@ -161,34 +127,4 @@ module RDoc::Generator::Markdown::Signatures
     parts << current.strip unless current.empty?
     parts
   end
-
-  # Checks whether a character separates top-level signature parts.
-  #
-  # @param char [String] Current signature character.
-  # @param delimiters [Array<String>] Expected closing delimiters.
-  #
-  # @return [Boolean] Whether the character is a top-level comma.
-  def self.top_level_signature_separator?(char, delimiters)
-    char == "," && delimiters.empty?
-  end
-
-  # Extracts a bare Ruby parameter name from a parameter fragment.
-  #
-  # @param parameter [String] Parameter fragment.
-  #
-  # @return [String, nil] Parameter name, or nil when invalid.
-  def self.extract_parameter_name(parameter)
-    match = parameter.match(/\A(?:\*\*|\*|&)?([a-z_]\w*):?\z/)
-    match && match[1]
-  end
-
-  # Checks whether a signature fragment already includes a parameter name.
-  #
-  # @param text [String] Signature fragment.
-  # @param name [String] Parameter name.
-  #
-  # @return [Boolean] True when the name appears as a standalone word.
-  def self.signature_part_mentions_name?(text, name)
-    text.match?(/(?<!\w)#{name}(?!\w)/)
-  end
 end

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

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+require "cgi"
+
+# Small GFM primitives shared by native markup and the HTML input boundary.
+module RDoc::Generator::Markdown::Syntax
+  # Maps Commonmarker's one-based UTF-8 byte columns to Ruby byte ranges.
+  # @param node [Commonmarker::Node] Parsed node with source positions.
+  # @param offsets [Array<Integer>] Byte offset of each source line.
+  # @return [Range<Integer>] Half-open source byte range.
+  def self.source_range(node, offsets)
+    start_line, start_column, end_line, end_column = node.source_position.fetch_values(:start_line, :start_column, :end_line, :end_column)
+    first = offsets.fetch(start_line - 1) + start_column - 1
+    last = offsets.fetch(end_line - 1) + end_column
+    first...last
+  end
+
+  # Uses RDoc's code-tag and escape rules to identify literal native source.
+  # @param text [String] Original inline source.
+  # @return [Array<Range<Integer>>] Literal native source byte ranges.
+  def self.native_literal_ranges(text)
+    ranges = []
+    text.b.scan(/\\[\\*_+`{}\[\]<>]|<(code|tt)>(?:\\.|[^\\])*?<\/\1>/) do
+      ranges << Range.new(*Regexp.last_match.offset(0), true)
+    end
+    ranges
+  end
+
+  # Protects native code tags and Markdown code spans during prose cleanup.
+  # @param text [String] Inline source encoded as UTF-8.
+  # @return [Array<Range<Integer>>] Literal source byte ranges.
+  def self.code_ranges(text)
+    offsets = [0]
+    text.each_line { |line| offsets << offsets.last + line.bytesize }
+    ranges = native_literal_ranges(text)
+    Commonmarker.parse(text).walk do |node|
+      ranges << source_range(node, offsets) if node.type == :code
+    end
+    ranges
+  end
+
+  # Checks a byte position against protected source spans.
+  # @param ranges [Array<Range<Integer>>] Literal source ranges.
+  # @param position [Integer] Source byte offset.
+  # @return [Boolean] Whether the position is inside literal content.
+  def self.literal_position?(ranges, position)
+    ranges.any? { |range| range.cover?(position) }
+  end
+
+  # Collects visible inline text without rendering Markdown through HTML.
+  # @param node [Commonmarker::Node] Parsed heading or image label.
+  # @return [String] Plain visible text, including soft and hard breaks.
+  def self.node_text(node)
+    text = +""
+    node.walk do |child|
+      case child.type
+      when :text, :code then text << child.string_content
+      when :softbreak, :linebreak then text << " "
+      end
+    end
+    text
+  end
+
+  # Escapes prose while retaining main's Markdown escape for semicolons.
+  # @param text [String] Literal prose, including block-looking definition terms.
+  # @return [String] Safe Markdown text.
+  def self.escape(text)
+    text.gsub(/[ \t]+/, " ").gsub(/[&`*_\[\]<>#]|\\(?!;)/) { |character| (character == "&") ? "&amp;" : "\\#{character}" }
+      .sub(/\A(\d+)\.(?=\s)/, '\1\\.')
+  end
+
+  # Wraps literal code with a delimiter that cannot occur in its contents.
+  # @param text [String] Literal code.
+  # @return [String] Native code span.
+  def self.code(text)
+    return "<code></code>" if text.empty?
+
+    fence = ""
+    fence += "`" while text.include?(fence)
+    content = (text.start_with?("`") || text.end_with?("`")) ? " #{text} " : text
+    "#{fence}#{content}#{fence}"
+  end
+
+  # Emits fenced code without interpreting its contents as prose.
+  # @param text [String] Literal code.
+  # @param language [String, Symbol, nil] Optional language metadata.
+  # @return [String] Fenced code block.
+  def self.code_block(text, language)
+    fence = "```"
+    fence += "`" while text.include?(fence)
+    "#{fence}#{language}\n#{text.rstrip}\n#{fence}"
+  end
+
+  # Emits an explicit, attribute-safe heading alias.
+  # @param id [String] Fragment identifier.
+  # @return [String] Empty HTML anchor.
+  def self.anchor(id)
+    %(<a id="#{CGI.escapeHTML(id)}"></a>)
+  end
+
+  # Formats a GFM heading and its explicit aliases.
+  # @param level [Integer] Requested heading level.
+  # @param text [String] Native inline Markdown.
+  # @param aliases [Array<String>] Additional heading IDs.
+  # @return [String] Heading capped at level six.
+  def self.heading(level, text, aliases)
+    "#{"#" * [level, 6].min} #{text}#{aliases.map { |id| anchor(id) }.join}"
+  end
+
+  # Maps legacy local HTML targets while preserving external URLs and fragments.
+  # @param href [String] Original target.
+  # @return [String] Markdown target.
+  def self.target(href)
+    return "https://#{href}" if href.start_with?("www.")
+    return href if href.match?(/\A(?:https?:\/\/|mailto:|#)/i)
+
+    href.sub(/\.html(?=[?#]|\z)/i, ".md")
+      .sub(%r{\A/(?=.+\.md(?:[?#]|\z))}, "")
+      .sub(%r{\A((?:\.\./)*)(?:files|classes|modules)/(?=.+\.md(?:[?#]|\z))}, '\1')
+  end
+
+  # Emits a link, restoring Ruby indexing expressions misparsed as tidy links.
+  # @param label [String] Native inline Markdown label.
+  # @param href [String] Original target.
+  # @return [String] Markdown link or literal code span.
+  def self.link(label, href)
+    receiver = label.delete("\\")
+    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/)
+      code("#{receiver}[#{href}]")
+    else
+      "[#{label}](#{target(href)})"
+    end
+  end
+end

data/lib/rdoc/generator/markdown.rb

@@ -1,10 +1,7 @@
 # frozen_string_literal: true
 
 require "erb"
-# standard:disable Lint/RedundantRequireStatement
-require "set"
-# standard:enable Lint/RedundantRequireStatement
-require "reverse_markdown"
+require "nokogiri"
 require "csv"
 require "fileutils"
 
@@ -12,9 +9,11 @@ require "fileutils"
 class RDoc::Generator::Markdown
   RDoc::RDoc.add_generator self
 
-  require_relative "markdown/conversion"
-  require_relative "markdown/crossref"
+  require_relative "markdown/syntax"
+  require_relative "markdown/references"
+  require_relative "markdown/html_input"
   require_relative "markdown/descriptions"
+  require_relative "markdown/formatter"
   require_relative "markdown/index"
   require_relative "markdown/paths"
   require_relative "markdown/selection"
@@ -23,14 +22,12 @@ class RDoc::Generator::Markdown
   include Descriptions
   include Index
   include Paths
-  include Signatures
 
   # Directory containing ERB templates.
   TEMPLATE_DIR = File.expand_path(File.join(File.dirname(__FILE__), "..", "..", "templates"))
 
   # Prepared objects and lookup tables used during one generation run.
   GenerationState = Data.define(
-    :output_dir,
     :classes,
     :pages,
     :class_output_paths,
@@ -44,20 +41,6 @@ class RDoc::Generator::Markdown
   # @return [RDoc::Store]
   attr_reader :store
 
-  # Classes and modules selected for output.
-  #
-  # @return [Array<RDoc::Context>, nil]
-  def classes
-    generation_state&.classes
-  end
-
-  # Text files selected for output.
-  #
-  # @return [Array<RDoc::TopLevel>, nil]
-  def pages
-    generation_state&.pages
-  end
-
   # Creates a generator for an RDoc store and options.
   #
   # @param store [RDoc::Store] Source documentation store.
@@ -87,28 +70,35 @@ class RDoc::Generator::Markdown
 
   private
 
-  attr_reader :generation_state, :options, :source_dir
+  attr_reader :generation_state, :options, :source_dir, :output_dir
 
-  # Builds an HTML anchor tag.
+  # Classes and modules selected for output.
   #
-  # @param id [String] Fragment identifier for the generated anchor.
+  # @return [Array<RDoc::Context>]
+  def classes
+    generation_state.classes
+  end
+
+  # Text files selected for output.
   #
-  # @return [String] HTML anchor tag.
-  def anchor(id)
-    %(<a id="#{id}"></a>)
+  # @return [Array<RDoc::TopLevel>]
+  def pages
+    generation_state.pages
   end
 
   # Applies final whitespace and link normalization before writing Markdown.
+  # Blank-line cleanup skips code: a fence is longer than any backtick run it contains.
   #
   # @param content [String] Markdown content.
   # @param current_output_path [String] Output path for the file being written.
   #
   # @return [String] Final Markdown ending with one newline.
   def finalize_markdown(content, current_output_path:)
-    normalized = normalize_internal_links(
+    normalized = Paths.rewrite_internal_links(
       content.lines.map(&:rstrip).join("\n"),
-      current_output_path: current_output_path
-    ).sub(/\n{3,}/, "\n\n").gsub(/^(#+ .+)\n\n/, "\\1\n")
+      current_output_path, generation_state
+    ).gsub(/(`{3,}).+?\1|\n{3,}/m) { ($1) ? $& : "\n\n" }
+      .gsub(/(`{3,}).+?\1|^(#+ [^\n]+)\n\n/m) { ($2) ? "#{$2}\n" : $& }
     "#{normalized}\n"
   end
 
@@ -153,7 +143,7 @@ class RDoc::Generator::Markdown
 
       next FileUtils.cp(File.expand_path(page.absolute_name, source_dir), out_file) if page.relative_name.match?(/\.(?:md|markdown)\z/i)
 
-      content = Conversion.markdownify(render_description(page))
+      content = describe(page)
       File.write(out_file, finalize_markdown(content, current_output_path: output_path))
     end
   end
@@ -162,30 +152,22 @@ class RDoc::Generator::Markdown
   #
   # @return [void]
   def setup
-    output_dir = options.op_dir
-    unless output_dir.instance_of?(String)
-      raise TypeError, "RDoc markdown output directory must be a String"
-    end
-
     classes = Selection.classes(store)
     class_output_paths = classes.to_h { |klass| [klass.full_name, output_path_for(klass)] }
     pages = Selection.pages(store)
+    known_output_paths = Set.new
+    (class_output_paths.values + pages.map { |page| page_output_path(page) }).each do |path|
+      warn "rdoc-markdown: several inputs write #{path}; only the last one is kept" unless known_output_paths.add?(path)
+    end
 
+    @output_dir = options.op_dir
     @generation_state = GenerationState.new(
-      output_dir: output_dir,
       classes: classes,
       pages: pages,
       class_output_paths: class_output_paths,
       markdown_output_object_ids: (classes + pages).to_set(&:object_id),
-      known_output_paths: class_output_paths.values.to_set.merge(pages.map { |page| page_output_path(page) }),
+      known_output_paths: known_output_paths,
       root_path_segment: Pathname.new(options.root || ".").basename
     )
   end
-
-  # Returns the prepared output directory.
-  #
-  # @return [String] Output directory.
-  def output_dir
-    generation_state.output_dir
-  end
 end

data/lib/rdoc/markdown/version.rb

@@ -5,6 +5,6 @@ module Rdoc
   # @private
   module Markdown
     # @private
-    VERSION = "0.21.1"
+    VERSION = "0.22.0"
   end
 end

data/lib/templates/classfile.md.erb

@@ -1,4 +1,4 @@
-# <%= klass.type.capitalize %> <%= klass.full_name %><%= anchor(klass.aref.strip) %>
+# <%= klass.type.capitalize %> <%= klass.full_name %><%= Syntax.anchor(klass.aref.strip) %>
 <%- superclass = klass.superclass if klass.type == "class" -%>
 <%- includes = klass.includes -%>
 <%- source_files = klass.in_files -%>
@@ -32,7 +32,7 @@
 
 <%= "#" * section_heading_level %> <%= section_title %>
 <%- end -%>
-<%- section_description = section_description(section, heading_level_offset: section_heading_level) -%>
+<%- section_description = render_description(section, heading_level_offset: section_heading_level) -%>
 <%- unless section_description.empty? -%>
 
 <%= section_description %>
@@ -42,7 +42,7 @@
 <%= "#" * group_heading_level %> Constants
 <% constants.sort_by(&:name).each do |const| -%>
 
-<%= "#" * member_heading_level %> `<%= const.name %>`<%= anchor(const.name) %>
+<%= "#" * member_heading_level %> `<%= const.name %>`<%= Syntax.anchor(const.name) %>
 <%= describe(const, fallback: "Not documented.", heading_level_offset: member_heading_level) %>
 <% end -%>
 <%- end -%>
@@ -51,7 +51,7 @@
 <%= "#" * group_heading_level %> Attributes
 <% attributes.sort_by(&:name).each do |attr| -%>
 
-<%= "#" * member_heading_level %> `<%= attr.name %>` [<%= attr.rw %>]<%= anchor(attr.aref.strip) %>
+<%= "#" * member_heading_level %> `<%= attr.name %>` [<%= attr.rw %>]<%= Syntax.anchor(attr.aref.strip) %>
 <%= describe(attr, fallback: "Not documented.", heading_level_offset: member_heading_level) %>
 <% end -%>
 <%- end -%>
@@ -63,7 +63,12 @@
 <%= "#" * group_heading_level %> <%= visibility.capitalize %> <%= type.capitalize %> Methods
 <% methods.each do |method| -%>
 
-<%= "#" * member_heading_level %> `<%= method_signature(method) %>`<%= anchor(method.aref) %>
+<%= "#" * member_heading_level %> <%= Syntax.code(Signatures.render_method_signature(method, store)) %><%= Syntax.anchor(method.aref) %>
+<%- aliases = method_aliases(method) -%>
+<%- if aliases -%>
+<%= aliases %>
+
+<%- end -%>
 <%= method_description(method, current_class: klass, heading_level_offset: member_heading_level) %>
 <% end -%>
 <% end -%>

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rdoc-markdown
 version: !ruby/object:Gem::Version
-  version: 0.21.1
+  version: 0.22.0
 platform: ruby
 authors:
 - Stanislav (Stas) Katkov
@@ -52,7 +52,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '8.0'
 - !ruby/object:Gem::Dependency
-  name: reverse_markdown
+  name: nokogiri
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -65,34 +65,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-- !ruby/object:Gem::Dependency
-  name: bundler
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '2.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '2.0'
 - !ruby/object:Gem::Dependency
   name: commonmarker
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
+        version: '2.8'
+  type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '2.8'
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
@@ -149,22 +135,8 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-- !ruby/object:Gem::Dependency
-  name: ruby-lsp
-  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'
-description: RDoc plugin to generate markdown documentation and search index as sqlite
-  database for entire content.
+description: RDoc plugin to generate markdown documentation and a CSV search index
+  for its entire content.
 email:
 - github@skatkov.com
 executables: []
@@ -174,16 +146,21 @@ files:
 - CHANGELOG.md
 - LICENSE
 - README.md
-- lib/markdown.rb
 - lib/rdoc/discover.rb
 - lib/rdoc/generator/markdown.rb
-- lib/rdoc/generator/markdown/conversion.rb
-- lib/rdoc/generator/markdown/crossref.rb
+- lib/rdoc/generator/markdown/blocks.rb
 - lib/rdoc/generator/markdown/descriptions.rb
+- lib/rdoc/generator/markdown/formatter.rb
+- lib/rdoc/generator/markdown/html_input.rb
 - lib/rdoc/generator/markdown/index.rb
+- lib/rdoc/generator/markdown/inline.rb
+- lib/rdoc/generator/markdown/inline_html.rb
+- lib/rdoc/generator/markdown/markdown_links.rb
 - lib/rdoc/generator/markdown/paths.rb
+- lib/rdoc/generator/markdown/references.rb
 - lib/rdoc/generator/markdown/selection.rb
 - lib/rdoc/generator/markdown/signatures.rb
+- lib/rdoc/generator/markdown/syntax.rb
 - lib/rdoc/markdown/version.rb
 - lib/templates/classfile.md.erb
 - sig/rdoc/markdown.rbs
@@ -193,7 +170,7 @@ licenses:
 metadata:
   homepage_uri: https://poshtui.com
   source_code_uri: https://github.com/skatkov/rdoc-markdown
-  changelog_uri: https://github.com/skatkov/rdoc-markdown
+  changelog_uri: https://github.com/skatkov/rdoc-markdown/blob/main/CHANGELOG.md
 rdoc_options: []
 require_paths:
 - lib
@@ -208,7 +185,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.19
+rubygems_version: 4.0.20
 specification_version: 4
 summary: RDoc plugin to generate markdown documentation
 test_files: []

data/lib/markdown.rb

@@ -1,3 +0,0 @@
-# frozen_string_literal: true
-
-require "rdoc/generator/markdown"