rdoc-markdown 0.17.2 → 0.19.0

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

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+# Resolves source and generated documentation paths.
+module RDoc::Generator::Markdown::Paths
+  # Converts a qualified object name into a Markdown path.
+  #
+  # @param class_name [String] Qualified class or module name.
+  #
+  # @return [String] Relative Markdown path.
+  def turn_to_path(class_name)
+    "#{class_name.gsub("::", "/")}.md"
+  end
+
+  # Builds the Markdown output path for an RDoc page.
+  #
+  # @param page [RDoc::TopLevel] Page object to render.
+  #
+  # @return [String] Relative Markdown path.
+  def page_output_path(page)
+    relative_name = page.relative_name
+    source_path = normalize_input_path_for_output(relative_name)
+    return source_path if relative_name.match?(/\.(?:md|markdown)\z/i)
+
+    dirname = File.dirname(source_path)
+    basename = "#{File.basename(source_path).tr(".", "_")}.md"
+
+    return basename if dirname == "."
+
+    "#{dirname}/#{basename}"
+  end
+
+  # Returns the canonical Markdown path for a class or module.
+  #
+  # @param code_object [RDoc::Context] Class or module object.
+  #
+  # @return [String] Relative Markdown path.
+  def output_path_for(code_object)
+    turn_to_path(code_object.full_name)
+  end
+
+  # Rewrites local Markdown links relative to the current output file.
+  #
+  # @param markdown [String] Markdown content.
+  # @param current_output_path [String] Output path for the file being written.
+  #
+  # @return [String] Markdown with normalized internal links.
+  def normalize_internal_links(markdown, current_output_path:)
+    RDoc::Generator::Markdown::Paths.rewrite_internal_links(
+      markdown,
+      current_output_path,
+      generation_state
+    )
+  end
+
+  private :turn_to_path, :page_output_path, :output_path_for, :normalize_internal_links
+
+  # Rewrites links using explicit generated-path state.
+  #
+  # @param markdown [String] Markdown content.
+  # @param current_output_path [String] Output path for the current file.
+  # @param state [RDoc::Generator::Markdown::GenerationState] Prepared generation state.
+  #
+  # @return [String] Markdown with normalized internal links.
+  def self.rewrite_internal_links(markdown, current_output_path, state)
+    current_dir = Pathname.new(current_output_path).dirname
+
+    markdown.gsub(%r{\]\(([^)]+)\)}) do
+      target = Regexp.last_match(1)
+      path = target.sub(/[?#].*\z/, "")
+      suffix = target[path.length..]
+
+      resolved = resolve_output_path_from(path, current_dir, state)
+      rewritten = resolved ? Pathname.new(resolved).relative_path_from(current_dir) : path
+      "](#{rewritten}#{suffix})"
+    end
+  end
+
+  # Resolves a link against explicit generated-path state.
+  #
+  # @param path [String] Link path from Markdown content.
+  # @param current_dir [Pathname] Directory of the current output file.
+  # @param state [RDoc::Generator::Markdown::GenerationState] Prepared generation state.
+  #
+  # @return [String, nil] Resolved output path, or nil when unresolved.
+  def self.resolve_output_path_from(path, current_dir, state)
+    candidates = [path, path.delete_prefix("#{state.root_path_segment}/")]
+    candidates += candidates.map { |candidate| candidate.sub(/_(md|markdown)\.md\z/i, '.\1') }
+    expanded_candidates = candidates.map { |candidate| current_dir.join(candidate).cleanpath.to_s }
+
+    (candidates + expanded_candidates).find { |candidate| state.known_output_paths.include?(candidate) }
+  end
+
+  # Normalizes an input filename into an output-relative source path.
+  #
+  # @param path [String] RDoc input path.
+  #
+  # @return [String] Normalized path without root prefixes.
+  def normalize_input_path_for_output(path)
+    RDoc::Generator::Markdown::Paths.normalize_input_path(path, source_dir)
+  end
+
+  private :normalize_input_path_for_output
+
+  # Normalizes an input path against an explicit source directory.
+  #
+  # @param path [String] RDoc input path.
+  # @param source_dir [String] Absolute documentation source directory.
+  #
+  # @return [String] Normalized path without root prefixes.
+  def self.normalize_input_path(path, source_dir)
+    normalized = path.tr("\\", "/").sub(%r{\A\./}, "")
+    normalized = normalized.sub(%r{\A#{Regexp.escape(source_dir)}/}, "")
+    normalized = normalized.sub(%r{\A/}, "")
+
+    root_basename = File.basename(source_dir)
+    normalized.sub(%r{\A#{Regexp.escape(root_basename)}/}, "")
+  end
+end

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

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+# Selects RDoc objects that produce Markdown output.
+module RDoc::Generator::Markdown::Selection
+  # Returns sorted classes and modules with renderable content.
+  #
+  # @param store [RDoc::Store] Documentation store.
+  #
+  # @return [Array<RDoc::Context>] Selected classes and modules.
+  def self.classes(store)
+    store.unique_classes_and_modules.select(&:display?).select { |klass| renderable_class?(klass) }.sort
+  end
+
+  # Checks whether a class or module has content worth rendering.
+  #
+  # @param klass [RDoc::Context] Candidate class or module.
+  #
+  # @return [Boolean] Whether the object should produce a page.
+  def self.renderable_class?(klass)
+    klass.in_files.any? ||
+      klass.documented? ||
+      klass.includes.any? ||
+      klass.method_list.any?(&:display?) ||
+      klass.constants.any?(&:display?) ||
+      klass.attributes.any?(&:display?) ||
+      klass.sections.any? { |section| section.title.to_s.match?(/\S/) || !section.to_document.empty? }
+  end
+
+  # Returns sorted documentation pages supported by the generator.
+  #
+  # @param store [RDoc::Store] Documentation store.
+  #
+  # @return [Array<RDoc::TopLevel>] Selected pages.
+  def self.pages(store)
+    store.all_files.select(&:text?).select(&:display?)
+      .select { |page| page.relative_name.match?(/\.(?:md|markdown|rdoc)\z/i) }
+      .sort_by(&:base_name)
+  end
+end

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

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+# Normalizes RDoc and RBS method signatures for headings.
+module RDoc::Generator::Markdown::Signatures
+  # Signature opening delimiters and their matching closers.
+  DELIMITER_PAIRS = {
+    "(" => ")", "[" => "]", "{" => "}"
+  }.freeze
+
+  # Builds the visible method signature used in headings.
+  #
+  # @param method [RDoc::AnyMethod] Method object to render.
+  #
+  # @return [String] Normalized method signature.
+  def method_signature(method)
+    RDoc::Generator::Markdown::Signatures.render_method_signature(method, store)
+  end
+
+  private :method_signature
+
+  # Builds a method signature from RDoc and store metadata.
+  #
+  # @param method [RDoc::AnyMethod] Method object to render.
+  # @param store [RDoc::Store] Documentation store with sidecar signatures.
+  #
+  # @return [String] Normalized method signature.
+  def self.render_method_signature(method, store)
+    signatures = method.type_signature_lines || store.rbs_signature_for(method) || [method.param_seq]
+
+    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
+
+  # Merges RDoc parameter names into a type-only signature.
+  #
+  # @param signature [String] Method signature from RDoc call sequence.
+  # @param raw_params [String, nil] Method parameter list from RDoc.
+  #
+  # @return [String] Signature with names added when safe.
+  def self.merge_method_signature_arguments(signature, raw_params)
+    params = normalized_method_params(raw_params)
+
+    signature_args, signature_suffix = split_signature_arguments_and_suffix(signature)
+    return signature unless signature_args
+
+    param_parts = split_signature_list(params)
+    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
+  end
+
+  # Merges matching parameter and signature fragments.
+  #
+  # @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) }
+    return if param_names.any?(&:nil?)
+    return if signature_parts.zip(param_names).all? { |part, name| signature_part_mentions_name?(part, name) }
+
+    merged_args = param_parts.zip(signature_parts).map do |param, type|
+      separator = param.end_with?(":") ? " " : ": "
+      "#{param}#{separator}#{type}"
+    end
+
+    "(#{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.
+  #
+  # @return [Array<String>, nil] Argument text and suffix, or nil when not parenthesized.
+  def self.split_signature_arguments_and_suffix(signature)
+    return unless signature.start_with?("(")
+
+    depth = 0
+
+    signature.each_char.with_index do |char, index|
+      depth += 1 if char == "("
+
+      next unless char == ")"
+
+      depth -= 1
+      return [signature[1...index], signature[(index + 1)..]] if depth.zero?
+    end
+  end
+
+  # Splits a comma-separated signature list while preserving nested groups.
+  #
+  # @param list [String] Signature argument list.
+  #
+  # @return [Array<String>] Signature parts.
+  def self.split_signature_list(list)
+    parts = []
+    current = +""
+    delimiters = []
+
+    list.each_char do |char|
+      if top_level_signature_separator?(char, delimiters)
+        parts << current.strip
+        current.clear
+      else
+        closing = DELIMITER_PAIRS[char]
+        if closing
+          delimiters << closing
+        elsif char == delimiters.last
+          delimiters.pop
+        end
+        current << char
+      end
+    end
+
+    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