yard-markdown 0.6.0 → 0.7.1

data/lib/yard/markdown/collection_rendering_helper.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module YARD
+  module Markdown
+    # Renders grouped Markdown sections for constants, attributes, and methods.
+    module CollectionRenderingHelper
+      # Renders the constants section for an object page.
+      #
+      # @param constants [Array<YARD::CodeObjects::Base>] Constant objects collected for the current page.
+      # @param group_order [Array<String>, nil] Preferred ordering for group headings.
+      # @return [String] Markdown for the constants section.
+      def render_constants(constants, group_order)
+        lines = ["## Constants"]
+        grouped_constants = grouped_items(constants.sort_by { |item| item.name }, group_order)
+        uses_groups = grouped_constants.any? { |name, _items| !name.nil? }
+
+        grouped_constants.each do |group_name, items|
+          if uses_groups
+            lines << "### #{group_name || "General"}"
+            item_heading = "####"
+          else
+            item_heading = "###"
+          end
+
+          lines << items.map { |item|
+            item_lines = [heading_with_anchors("#{item_heading} `#{item.name}`", item)]
+            append_lines(item_lines, documented_text(item), separated: false)
+            append_lines(item_lines, render_tags(item), separated: false)
+            item_lines.join("\n")
+          }.join("\n\n")
+        end
+
+        lines.join("\n")
+      end
+
+      # Renders the attributes section for an object page.
+      #
+      # @param attrs [Array<YARD::CodeObjects::MethodObject>] Attributes to render.
+      # @param group_order [Array<String>, nil] Preferred ordering for group headings.
+      # @return [String] Markdown for the attributes section.
+      def render_attributes(attrs, group_order)
+        lines = ["## Attributes"]
+        grouped_attrs = grouped_items(attrs, group_order)
+        uses_groups = grouped_attrs.any? { |name, _items| !name.nil? }
+
+        grouped_attrs.each do |group_name, items|
+          if uses_groups
+            lines << "### #{group_name || "General"}"
+            item_heading = "####"
+          else
+            item_heading = "###"
+          end
+
+          lines << items.map { |item|
+            item_lines = [heading_with_anchors("#{item_heading} `#{item.name}` [#{attribute_access(item)}]", item)]
+            append_lines(item_lines, documented_text(item), separated: false)
+            append_lines(item_lines, render_tags(item), separated: false)
+            item_lines.join("\n")
+          }.join("\n\n")
+        end
+
+        lines.join("\n")
+      end
+
+      # Renders a method section for an object page.
+      #
+      # @param section_title [String] Section title to render.
+      # @param methods [Array<YARD::CodeObjects::MethodObject>] Method objects collected for the current section.
+      # @param group_order [Array<String>, nil] Preferred ordering for group headings.
+      # @return [String] Markdown for the method section.
+      def render_methods(section_title, methods, group_order)
+        lines = ["## #{section_title}"]
+        grouped_methods = grouped_items(methods, group_order)
+        uses_groups = grouped_methods.any? { |name, _items| !name.nil? }
+
+        grouped_methods.each do |group_name, items|
+          if uses_groups
+            lines << "### #{group_name || "General"}"
+            item_heading = "####"
+          else
+            item_heading = "###"
+          end
+
+          lines << items.map { |item|
+            item_lines = [heading_with_anchors("#{item_heading} `#{formatted_method_heading(item)}`", item)]
+            append_lines(item_lines, documented_text(item), separated: false)
+            append_lines(item_lines, render_tags(item), separated: false)
+            item_lines.join("\n")
+          }.join("\n\n")
+        end
+
+        lines.join("\n")
+      end
+    end
+  end
+end

data/lib/yard/markdown/documentation_helper.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "rdoc"
+
+module YARD
+  module Markdown
+    # Converts YARD docstrings into Markdown-friendly text.
+    module DocumentationHelper
+      # Returns the rendered documentation text for an object.
+      #
+      # @param object [YARD::CodeObjects::Base] Object whose docstring is being rendered.
+      # @return [String] Converted documentation text or a fallback message.
+      def documented_text(object)
+        text = rdoc_to_md(object.docstring)
+        return text unless text.empty?
+        return "" unless object.tags.empty?
+
+        "Not documented."
+      end
+
+      # Converts an RDoc-formatted docstring to Markdown.
+      #
+      # @param docstring [Object] Raw docstring content.
+      # @return [String] Markdown-rendered docstring content.
+      def rdoc_to_md(docstring)
+        fenced_code_blocks = []
+        placeholder = "YARD_MARKDOWN_FENCED_CODE_BLOCK_%d"
+        content = docstring.gsub(/^```[^\n]*\n.*?^```[ \t]*$/m) do |block|
+          fenced_code_blocks << block
+          format(placeholder, fenced_code_blocks.length - 1)
+        end
+
+        markdown = RDoc::Markup::ToMarkdown.new.convert(content).rstrip
+        fenced_code_blocks.each_with_index do |block, index|
+          markdown = markdown.sub(format(placeholder, index), block)
+        end
+
+        markdown
+      end
+    end
+  end
+end

data/lib/yard/markdown/heading_helper.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module YARD
+  module Markdown
+    # Builds headings and legacy anchors for rendered object sections.
+    module HeadingHelper
+      include ArefHelper
+
+      # Returns the legacy YARD anchor for an object when one exists.
+      #
+      # @param object [YARD::CodeObjects::Base] Object being rendered.
+      # @return [String, nil] Legacy anchor id, if supported.
+      def legacy_aref(object)
+        type = object.type
+
+        return "#{object.name}-constant" if type == :constant
+        return "#{object.name}-classvariable" if type == :classvariable
+        return nil unless object.respond_to?(:scope)
+
+        return "#{object.name}-class_method" if object.scope == :class
+
+        "#{object.name}-instance_method"
+      end
+
+      # Returns all anchor tags that should be attached to a heading.
+      #
+      # @param object [YARD::CodeObjects::Base] Object being rendered.
+      # @return [Array<String>] HTML anchor tags for the object.
+      def anchor_tags_for(object)
+        anchors = [aref(object), legacy_aref(object)].compact
+        anchors.map { |id| anchor_tag(id) }
+      end
+
+      # Appends the generated anchor tags to a Markdown heading.
+      #
+      # @param heading [String] Heading text to decorate.
+      # @param object [YARD::CodeObjects::Base] Object being rendered.
+      # @return [String] Heading text with embedded anchor tags.
+      def heading_with_anchors(heading, object)
+        "#{heading} #{anchor_tags_for(object).join(" ")}"
+      end
+
+      # Builds an HTML anchor tag for a generated id.
+      #
+      # @param id [String] Anchor id value.
+      # @return [String] HTML anchor tag.
+      def anchor_tag(id)
+        %(<a id="#{id}"></a>)
+      end
+    end
+  end
+end

data/lib/yard/markdown/link_normalization_helper.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+module YARD
+  module Markdown
+    # Rewrites generated Markdown links so they point at Markdown output.
+    module LinkNormalizationHelper
+      # Normalizes generated Markdown before it is written to disk.
+      #
+      # @param content [String, Array<String>] Markdown content to finalize.
+      # @param current_path [String] Output path for the current document.
+      # @return [String] Normalized Markdown content with a trailing newline.
+      def finalize_markdown(content, current_path)
+        output = content.instance_of?(Array) ? content.join("\n") : content
+        output = output.lines.map(&:rstrip).join("\n")
+        output = normalize_local_links(output, current_path)
+        output = normalize_malformed_local_links(output)
+        output = output.gsub(/\n{3,}/, "\n\n").strip
+        "#{output}\n"
+      end
+
+      # Rewrites local Markdown links relative to the current output path.
+      #
+      # @param markdown [String] Markdown content to rewrite.
+      # @param current_path [String] Output path for the current document.
+      # @return [String] Markdown with local links normalized.
+      def normalize_local_links(markdown, current_path)
+        current_dir = Pathname.new(current_path).dirname
+
+        markdown.gsub(%r{\[(.+?)\]\((?!https?://|mailto:|#)([^)\n]+)\)}) do
+          label = Regexp.last_match(1)
+          target = Regexp.last_match(2)
+          path = target.sub(/[?#].*\z/, "")
+          suffix = target[path.length..]
+          rewritten_path = resolve_local_link_target(path, current_dir)
+
+          if rewritten_path.nil?
+            "`#{label.tr("`", "")}`"
+          else
+            "[#{label}](#{rewritten_path}#{suffix})"
+          end
+        end
+      end
+
+      # Resolves a local link path to a YARD registry object when possible.
+      #
+      # @param path [String] Link target path to resolve.
+      # @param current_dir [Pathname] Directory for the current output file.
+      # @return [YARD::CodeObjects::Base, nil] Matched registry object, if any.
+      def resolve_registry_object(path, current_dir)
+        cleaned = path.sub(%r{\A(?:(?:\.\./)+|\./)}, "")
+        candidates = [path]
+
+        if constant_reference_path?(cleaned)
+          current_parts = current_dir.to_s.split("/").reject { |part| part.empty? || part == "." }
+          target_parts = cleaned.split("/")
+
+          current_parts.length.downto(0) do |depth|
+            candidates << (current_parts.first(depth) + target_parts).join("::")
+          end
+        end
+
+        candidates.each do |candidate|
+          obj = Registry.at(candidate)
+          next if obj.nil? || obj.equal?(Registry.root)
+
+          return obj
+        end
+
+        nil
+      end
+
+      # Resolves a local link target to the final relative Markdown path.
+      #
+      # @param path [String] Link target path to resolve.
+      # @param current_dir [Pathname] Directory for the current output file.
+      # @return [String, nil] Relative Markdown path, or nil when unresolved.
+      def resolve_local_link_target(path, current_dir)
+        normalized = path.sub(%r{\A/+}, "")
+
+        obj = resolve_registry_object(normalized, current_dir)
+        if obj
+          object_path = options.serializer.serialized_path(obj)
+          return relative_output_path(current_dir, object_path)
+        end
+
+        if normalized.match?(/\.html\z/i)
+          normalized = normalized.sub(/\.html\z/i, ".md")
+        elsif File.extname(normalized).empty?
+          return nil if unresolved_identifier_target?(normalized)
+
+          normalized = "#{normalized}.md" if normalized.include?("/")
+        end
+
+        relative_output_path(current_dir, normalized)
+      end
+
+      # Returns whether a path looks like a constant reference.
+      #
+      # @param value [String] Link target to inspect.
+      # @return [Boolean] True when the path resembles a constant name.
+      def constant_reference_path?(value)
+        parts = value.split(%r{::|/}).reject(&:empty?)
+        return false if parts.empty?
+
+        parts.all? { |part| part.match?(/\A[A-Z]\w*\z/) }
+      end
+
+      # Returns whether a path looks like an unresolved bare identifier.
+      #
+      # @param path [String] Link target to inspect.
+      # @return [Boolean] True when the target should be treated as unresolved.
+      def unresolved_identifier_target?(path)
+        cleaned = path.sub(%r{\A(?:(?:\.\./)+|\./)}, "")
+        return true if cleaned.start_with?(":") || cleaned.match?(/\A\d/)
+
+        cleaned.match?(/\A[a-z_]\w*\z/)
+      end
+
+      # Computes a relative path from the current output directory.
+      #
+      # @param current_dir [Pathname] Directory for the current output file.
+      # @param target_path [String, Pathname] Output path being linked to.
+      # @return [String] Relative path suitable for a Markdown link.
+      def relative_output_path(current_dir, target_path)
+        target = target_path.to_s
+        return target if target.start_with?("../")
+
+        Pathname.new(target).relative_path_from(current_dir).to_s
+      rescue
+        target
+      end
+
+      # Replaces malformed local Markdown links with inline code.
+      #
+      # @param markdown [String] Markdown content to normalize.
+      # @return [String] Markdown with malformed local links replaced.
+      def normalize_malformed_local_links(markdown)
+        markdown.gsub(%r{\[([^\]]+)\]\((?!https?://|mailto:|#)(?:[^)\n]*['"][^)\n]*)\)}, '`\1`')
+      end
+    end
+  end
+end

data/lib/yard/markdown/method_presentation_helper.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module YARD
+  module Markdown
+    # Formats method and attribute names for Markdown headings.
+    module MethodPresentationHelper
+      # Builds the display heading for a method.
+      #
+      # @param method_object [YARD::CodeObjects::MethodObject] Method being rendered.
+      # @return [String] Method heading text.
+      def formatted_method_heading(method_object)
+        name = method_object.name
+        signature = method_signature(method_object)
+        signature = " #{signature}" if name.end_with?("]")
+        "#{name}#{signature}"
+      end
+
+      # Returns the rendered parameter list for a method.
+      #
+      # @param method_object [YARD::CodeObjects::MethodObject] Method being rendered.
+      # @return [String] Parenthesized method signature.
+      def method_signature(method_object)
+        return "()" if method_object.parameters.nil?
+
+        rendered = method_object.parameters.map do |name, default|
+          (default.nil? || default.empty?) ? name : "#{name} = #{default}"
+        end
+
+        "(#{rendered.join(", ")})"
+      end
+
+      # Returns the access marker for an attribute.
+      #
+      # @param attribute [YARD::CodeObjects::MethodObject] Attribute reader or writer.
+      # @return [String] Access mode marker such as `R`, `W`, or `RW`.
+      def attribute_access(attribute)
+        info = attribute.attr_info || {}
+        return "RW" if info[:read] && info[:write]
+        return "R" if info[:read]
+        return "W" if info[:write]
+
+        return "RW" if attribute.reader? && attribute.writer?
+        return "R" if attribute.reader?
+
+        "W"
+      end
+    end
+  end
+end

data/lib/yard/markdown/object_listing_helper.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module YARD
+  module Markdown
+    # Collects and sorts the objects shown on a rendered object page.
+    module ObjectListingHelper
+      # Returns the constants and class variables defined on an object.
+      #
+      # @param object [YARD::CodeObjects::NamespaceObject] Object being rendered.
+      # @return [Array<YARD::CodeObjects::Base>] Constants and class variables.
+      def constant_listing(object)
+        constants = object.constants(included: false, inherited: false)
+        constants + object.cvars
+      end
+
+      # Returns the visible public methods defined directly on an object.
+      #
+      # @param object [YARD::CodeObjects::NamespaceObject] Object being rendered.
+      # @return [Array<YARD::CodeObjects::MethodObject>] Sorted public methods.
+      def public_method_list(object)
+        prune_method_listing(object.meths(inherited: false, visibility: :public))
+          .reject { |item| hidden_object?(item) }
+          .sort_by { |method_object| method_object.name }
+      end
+
+      # Returns the public class methods defined directly on an object.
+      #
+      # @param object [YARD::CodeObjects::NamespaceObject] Object being rendered.
+      # @return [Array<YARD::CodeObjects::MethodObject>] Sorted public class methods.
+      def public_class_methods(object)
+        public_method_list(object).select { |item| item.scope == :class }
+      end
+
+      # Returns the public instance methods defined directly on an object.
+      #
+      # @param object [YARD::CodeObjects::NamespaceObject] Object being rendered.
+      # @return [Array<YARD::CodeObjects::MethodObject>] Sorted public instance methods.
+      def public_instance_methods(object)
+        public_method_list(object).select { |item| item.scope == :instance }
+      end
+
+      # Returns the visible attribute methods for an object.
+      #
+      # @param object [YARD::CodeObjects::NamespaceObject] Object being rendered.
+      # @return [Array<YARD::CodeObjects::MethodObject>] Sorted attribute methods.
+      def attr_listing(object)
+        attrs = []
+
+        object.inheritance_tree(true).each do |superclass|
+          next if !options.embed_mixins.empty? && !options.embed_mixins_match?(superclass)
+
+          %i[class instance].each do |scope|
+            superclass.attributes.fetch(scope).each do |_name, rw|
+              attr = prune_method_listing([rw.fetch(:read), rw.fetch(:write)].compact, false).first
+              attrs << attr if attr
+            end
+          end
+
+          break if options.embed_mixins.empty?
+        end
+
+        sort_listing(attrs)
+      end
+
+      # Sorts a listing by scope and case-insensitive name.
+      #
+      # @param list [Array<YARD::CodeObjects::Base>] Objects to sort.
+      # @return [Array<YARD::CodeObjects::Base>] Sorted objects.
+      def sort_listing(list)
+        list.sort do |left, right|
+          scope_comparison = left.scope <=> right.scope
+          next scope_comparison unless scope_comparison.zero?
+
+          left.name.to_s.casecmp(right.name.to_s)
+        end
+      end
+
+      # Returns whether an object is explicitly hidden with `:nodoc:`.
+      #
+      # @param object [YARD::CodeObjects::Base] Listed object whose docstring may start with `:nodoc:`.
+      # @return [Boolean] True when the object should be hidden.
+      def hidden_object?(object)
+        object.docstring.start_with?(":nodoc:")
+      end
+    end
+  end
+end

data/lib/yard/markdown/relationship_section_helper.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module YARD
+  module Markdown
+    # Renders inheritance and mixin relationship summaries.
+    module RelationshipSectionHelper
+      # Returns section content with the expected trailing spacing.
+      #
+      # @param content [Object] Section content to render.
+      # @return [String] Section content followed by blank-line spacing.
+      def render_section_content(content)
+        text = content.to_s.strip
+        return "" if text.empty?
+
+        "#{text}\n\n"
+      end
+
+      # Returns inheritance and mixin relationships for an object.
+      #
+      # @param object [YARD::CodeObjects::NamespaceObject] Object being rendered.
+      # @return [String] Markdown summary of the object's relationships.
+      def object_relationships(object)
+        lines = []
+
+        lines << "**Inherits:** `#{object.superclass}`" if object.instance_of?(CodeObjects::ClassObject)
+
+        [[:class, "Extended by"], [:instance, "Includes"]].each do |scope, label|
+          mixins = run_verifier(object.mixins(scope)).sort_by { |item| item.path }
+          next if mixins.empty?
+
+          lines << "**#{label}:** #{mixins.map { |mixin| "`#{mixin.path}`" }.join(", ")}"
+        end
+
+        lines.join("\n")
+      end
+    end
+  end
+end

data/lib/yard/markdown/section_assembly_helper.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module YARD
+  module Markdown
+    # Assembles grouped content into ordered Markdown sections.
+    module SectionAssemblyHelper
+      # Groups items by their YARD group and orders them for rendering.
+      #
+      # @param items [Array<#group>] Renderable objects that expose a YARD group name.
+      # @param group_order [Array<String>, nil] Preferred ordering for named groups.
+      # @return [Array<Array>] Ordered pairs of group names and grouped items.
+      def grouped_items(items, group_order)
+        grouped = Hash.new { |hash, key| hash[key] = [] }
+        items.each { |item| grouped[item.group] << item }
+
+        ordered = []
+
+        Array(group_order).each do |name|
+          next unless grouped.key?(name)
+
+          ordered << [name, grouped.delete(name)]
+        end
+
+        grouped.keys.compact.sort.each do |name|
+          ordered << [name, grouped.delete(name)]
+        end
+
+        ordered << [nil, grouped.delete(nil)] if grouped.key?(nil)
+        ordered
+      end
+
+      # Appends non-empty content to a mutable list of lines.
+      #
+      # @param lines [Array<String>] Destination line buffer.
+      # @param content [String] Rendered Markdown block to split into lines.
+      # @param separated [Boolean] Whether to insert a blank separator line first.
+      # @return [void]
+      def append_lines(lines, content, separated: true)
+        return if content.lstrip.empty?
+
+        lines << "" if separated && !lines.empty? && !lines.last.empty?
+        lines.concat(content.split("\n"))
+      end
+    end
+  end
+end

data/lib/yard/markdown/tag_formatting_helper.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module YARD
+  module Markdown
+    # Formats YARD tags into Markdown list items and fenced examples.
+    module TagFormattingHelper
+      # Renders all tags for an object as Markdown.
+      #
+      # @param object [YARD::CodeObjects::Base] Object whose tags are being rendered.
+      # @return [String] Markdown representation of the object's tags.
+      def render_tags(object)
+        lines = []
+        regular_tags = object.tags.reject { |tag| tag.tag_name == "example" }
+        example_tags = object.tags.select { |tag| tag.tag_name == "example" }
+
+        regular_tags.each do |tag|
+          lines << "- #{format_tag(tag)}"
+        end
+
+        example_tags.each do |tag|
+          lines << nil unless lines.empty?
+          title = tag.name.to_s.rstrip.empty? ? "**@example**" : "**@example #{tag.name}**"
+          lines << title
+          lines << "```ruby"
+          lines << tag.text.to_s.rstrip
+          lines << "```"
+        end
+
+        lines.join("\n")
+      end
+
+      # Formats a non-example YARD tag as a Markdown list item body.
+      #
+      # @param tag [YARD::Tags::Tag] Non-example tag being converted into list item text.
+      # @return [String] Markdown representation of the tag.
+      def format_tag(tag)
+        parts = ["**@#{tag.tag_name}**"]
+        parts << "`#{tag.name}`" unless tag.name.to_s.lstrip.empty?
+
+        cleaned_types = normalized_tag_types(tag.types)
+        parts << "[#{cleaned_types.join(", ")}]" unless cleaned_types.empty?
+        parts << tag.text.strip unless tag.text.to_s.lstrip.empty?
+
+        parts.join(" ")
+      end
+
+      # Normalizes tag type declarations into printable strings.
+      #
+      # @param types [Array<Object>, Hash, nil] Raw tag types from YARD.
+      # @return [Array<String>] Cleaned type strings.
+      def normalized_tag_types(types)
+        values = if types.instance_of?(Hash)
+          types.map { |name, value| format_hash_tag_type(name, value) }
+        else
+          Array(types)
+        end
+
+        values.map(&:to_s).map(&:strip).reject(&:empty?)
+      end
+
+      # Formats a hash-style tag type entry.
+      #
+      # @param name [String] Type name to format.
+      # @param value [Object] Associated type detail.
+      # @return [String, nil] Formatted type entry, or nil when blank.
+      def format_hash_tag_type(name, value)
+        key = name.rstrip
+        return nil if key.empty?
+        return key if value.nil? || value == true || (value.respond_to?(:empty?) && value.empty?)
+
+        "#{key}: #{value}"
+      end
+    end
+  end
+end

data/lib/yard-markdown.rb

@@ -1,6 +1,17 @@
 # frozen_string_literal: true
 
 require "yard"
+require_relative "yard/markdown/anchor_component_helper"
+require_relative "yard/markdown/aref_helper"
+require_relative "yard/markdown/collection_rendering_helper"
+require_relative "yard/markdown/documentation_helper"
+require_relative "yard/markdown/heading_helper"
+require_relative "yard/markdown/link_normalization_helper"
+require_relative "yard/markdown/method_presentation_helper"
+require_relative "yard/markdown/object_listing_helper"
+require_relative "yard/markdown/relationship_section_helper"
+require_relative "yard/markdown/section_assembly_helper"
+require_relative "yard/markdown/tag_formatting_helper"
 
 module YARD
   module Markdown