yard-markdown 0.6.0 → 0.7.0

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,144 @@
+# frozen_string_literal: true
+
+require 'pathname'
+
+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 StandardError
+        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.lstrip.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