yard-markdown 0.5.0 → 0.7.0

data/sig/yard/markdown.rbs

@@ -1,6 +1,348 @@
-module Yard
+# Namespace for YARD extensions used by this gem.
+module YARD
+  # Shared helpers for rendering YARD objects as Markdown.
   module Markdown
-    VERSION: String
-    # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+    # Computes anchor ids that match the generated Markdown headings.
+    module ArefHelper
+      include YARD::Markdown::AnchorComponentHelper
+
+      # Returns the primary anchor id for a documented object.
+      # 
+      # _@param_ `object` — Object being rendered.
+      # 
+      # _@return_ — Anchor id for the object's heading.
+      def aref: (untyped object) -> String
+
+      # Encodes a value so it can be embedded safely in an HTML anchor id.
+      # 
+      # _@param_ `value` — Raw anchor fragment to encode.
+      # 
+      # _@return_ — Anchor-safe identifier fragment.
+      def anchor_component: (Object value) -> String
+    end
+
+    # Builds headings and legacy anchors for rendered object sections.
+    module HeadingHelper
+      include YARD::Markdown::ArefHelper
+
+      # Returns the legacy YARD anchor for an object when one exists.
+      # 
+      # _@param_ `object` — Object being rendered.
+      # 
+      # _@return_ — Legacy anchor id, if supported.
+      def legacy_aref: (untyped object) -> String?
+
+      # Returns all anchor tags that should be attached to a heading.
+      # 
+      # _@param_ `object` — Object being rendered.
+      # 
+      # _@return_ — HTML anchor tags for the object.
+      def anchor_tags_for: (untyped object) -> ::Array[String]
+
+      # Appends the generated anchor tags to a Markdown heading.
+      # 
+      # _@param_ `heading` — Heading text to decorate.
+      # 
+      # _@param_ `object` — Object being rendered.
+      # 
+      # _@return_ — Heading text with embedded anchor tags.
+      def heading_with_anchors: (String heading, untyped object) -> String
+
+      # Builds an HTML anchor tag for a generated id.
+      # 
+      # _@param_ `id` — Anchor id value.
+      # 
+      # _@return_ — HTML anchor tag.
+      def anchor_tag: (String id) -> String
+
+      # Returns the primary anchor id for a documented object.
+      # 
+      # _@param_ `object` — Object being rendered.
+      # 
+      # _@return_ — Anchor id for the object's heading.
+      def aref: (untyped object) -> String
+
+      # Encodes a value so it can be embedded safely in an HTML anchor id.
+      # 
+      # _@param_ `value` — Raw anchor fragment to encode.
+      # 
+      # _@return_ — Anchor-safe identifier fragment.
+      def anchor_component: (Object value) -> String
+    end
+
+    # Converts YARD docstrings into Markdown-friendly text.
+    module DocumentationHelper
+      # Returns the rendered documentation text for an object.
+      # 
+      # _@param_ `object` — Object whose docstring is being rendered.
+      # 
+      # _@return_ — Converted documentation text or a fallback message.
+      def documented_text: (untyped object) -> String
+
+      # Converts an RDoc-formatted docstring to Markdown.
+      # 
+      # _@param_ `docstring` — Raw docstring content.
+      # 
+      # _@return_ — Markdown-rendered docstring content.
+      def rdoc_to_md: (Object docstring) -> String
+    end
+
+    # 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` — Object being rendered.
+      # 
+      # _@return_ — Constants and class variables.
+      def constant_listing: (untyped object) -> ::Array[untyped]
+
+      # Returns the visible public methods defined directly on an object.
+      # 
+      # _@param_ `object` — Object being rendered.
+      # 
+      # _@return_ — Sorted public methods.
+      def public_method_list: (untyped object) -> ::Array[untyped]
+
+      # Returns the public class methods defined directly on an object.
+      # 
+      # _@param_ `object` — Object being rendered.
+      # 
+      # _@return_ — Sorted public class methods.
+      def public_class_methods: (untyped object) -> ::Array[untyped]
+
+      # Returns the public instance methods defined directly on an object.
+      # 
+      # _@param_ `object` — Object being rendered.
+      # 
+      # _@return_ — Sorted public instance methods.
+      def public_instance_methods: (untyped object) -> ::Array[untyped]
+
+      # Returns the visible attribute methods for an object.
+      # 
+      # _@param_ `object` — Object being rendered.
+      # 
+      # _@return_ — Sorted attribute methods.
+      def attr_listing: (untyped object) -> ::Array[untyped]
+
+      # Sorts a listing by scope and case-insensitive name.
+      # 
+      # _@param_ `list` — Objects to sort.
+      # 
+      # _@return_ — Sorted objects.
+      def sort_listing: (::Array[untyped] list) -> ::Array[untyped]
+
+      # Returns whether an object is explicitly hidden with `:nodoc:`.
+      # 
+      # _@param_ `object` — Listed object whose docstring may start with `:nodoc:`.
+      # 
+      # _@return_ — True when the object should be hidden.
+      def hidden_object?: (untyped object) -> bool
+    end
+
+    # Formats YARD tags into Markdown list items and fenced examples.
+    module TagFormattingHelper
+      # Renders all tags for an object as Markdown.
+      # 
+      # _@param_ `object` — Object whose tags are being rendered.
+      # 
+      # _@return_ — Markdown representation of the object's tags.
+      def render_tags: (untyped object) -> String
+
+      # Formats a non-example YARD tag as a Markdown list item body.
+      # 
+      # _@param_ `tag` — Non-example tag being converted into list item text.
+      # 
+      # _@return_ — Markdown representation of the tag.
+      def format_tag: (untyped tag) -> String
+
+      # Normalizes tag type declarations into printable strings.
+      # 
+      # _@param_ `types` — Raw tag types from YARD.
+      # 
+      # _@return_ — Cleaned type strings.
+      def normalized_tag_types: ((::Array[Object] | ::Hash[untyped, untyped])? types) -> ::Array[String]
+
+      # Formats a hash-style tag type entry.
+      # 
+      # _@param_ `name` — Type name to format.
+      # 
+      # _@param_ `value` — Associated type detail.
+      # 
+      # _@return_ — Formatted type entry, or nil when blank.
+      def format_hash_tag_type: (String name, Object value) -> String?
+    end
+
+    # Builds anchor-safe identifier fragments from arbitrary values.
+    module AnchorComponentHelper
+      # Encodes a value so it can be embedded safely in an HTML anchor id.
+      # 
+      # _@param_ `value` — Raw anchor fragment to encode.
+      # 
+      # _@return_ — Anchor-safe identifier fragment.
+      def anchor_component: (Object value) -> String
+    end
+
+    # Assembles grouped content into ordered Markdown sections.
+    module SectionAssemblyHelper
+      # Groups items by their YARD group and orders them for rendering.
+      # 
+      # _@param_ `items` — Renderable objects that expose a YARD group name.
+      # 
+      # _@param_ `group_order` — Preferred ordering for named groups.
+      # 
+      # _@return_ — Ordered pairs of group names and grouped items.
+      def grouped_items: (::Array[untyped] items, ::Array[String]? group_order) -> ::Array[::Array[untyped]]
+
+      # Appends non-empty content to a mutable list of lines.
+      # 
+      # _@param_ `lines` — Destination line buffer.
+      # 
+      # _@param_ `content` — Rendered Markdown block to split into lines.
+      # 
+      # _@param_ `separated` — Whether to insert a blank separator line first.
+      def append_lines: (::Array[String] lines, String content, ?separated: bool) -> void
+    end
+
+    # Rewrites generated Markdown links so they point at Markdown output.
+    module LinkNormalizationHelper
+      # Normalizes generated Markdown before it is written to disk.
+      # 
+      # _@param_ `content` — Markdown content to finalize.
+      # 
+      # _@param_ `current_path` — Output path for the current document.
+      # 
+      # _@return_ — Normalized Markdown content with a trailing newline.
+      def finalize_markdown: ((String | ::Array[String]) content, String current_path) -> String
+
+      # Rewrites local Markdown links relative to the current output path.
+      # 
+      # _@param_ `markdown` — Markdown content to rewrite.
+      # 
+      # _@param_ `current_path` — Output path for the current document.
+      # 
+      # _@return_ — Markdown with local links normalized.
+      def normalize_local_links: (String markdown, String current_path) -> String
+
+      # Resolves a local link path to a YARD registry object when possible.
+      # 
+      # _@param_ `path` — Link target path to resolve.
+      # 
+      # _@param_ `current_dir` — Directory for the current output file.
+      # 
+      # _@return_ — Matched registry object, if any.
+      def resolve_registry_object: (String path, Pathname current_dir) -> untyped?
+
+      # Resolves a local link target to the final relative Markdown path.
+      # 
+      # _@param_ `path` — Link target path to resolve.
+      # 
+      # _@param_ `current_dir` — Directory for the current output file.
+      # 
+      # _@return_ — Relative Markdown path, or nil when unresolved.
+      def resolve_local_link_target: (String path, Pathname current_dir) -> String?
+
+      # Returns whether a path looks like a constant reference.
+      # 
+      # _@param_ `value` — Link target to inspect.
+      # 
+      # _@return_ — True when the path resembles a constant name.
+      def constant_reference_path?: (String value) -> bool
+
+      # Returns whether a path looks like an unresolved bare identifier.
+      # 
+      # _@param_ `path` — Link target to inspect.
+      # 
+      # _@return_ — True when the target should be treated as unresolved.
+      def unresolved_identifier_target?: (String path) -> bool
+
+      # Computes a relative path from the current output directory.
+      # 
+      # _@param_ `current_dir` — Directory for the current output file.
+      # 
+      # _@param_ `target_path` — Output path being linked to.
+      # 
+      # _@return_ — Relative path suitable for a Markdown link.
+      def relative_output_path: (Pathname current_dir, (String | Pathname) target_path) -> String
+
+      # Replaces malformed local Markdown links with inline code.
+      # 
+      # _@param_ `markdown` — Markdown content to normalize.
+      # 
+      # _@return_ — Markdown with malformed local links replaced.
+      def normalize_malformed_local_links: (String markdown) -> String
+    end
+
+    # Formats method and attribute names for Markdown headings.
+    module MethodPresentationHelper
+      # Builds the display heading for a method.
+      # 
+      # _@param_ `method_object` — Method being rendered.
+      # 
+      # _@return_ — Method heading text.
+      def formatted_method_heading: (untyped method_object) -> String
+
+      # Returns the rendered parameter list for a method.
+      # 
+      # _@param_ `method_object` — Method being rendered.
+      # 
+      # _@return_ — Parenthesized method signature.
+      def method_signature: (untyped method_object) -> String
+
+      # Returns the access marker for an attribute.
+      # 
+      # _@param_ `attribute` — Attribute reader or writer.
+      # 
+      # _@return_ — Access mode marker such as `R`, `W`, or `RW`.
+      def attribute_access: (untyped attribute) -> String
+    end
+
+    # Renders grouped Markdown sections for constants, attributes, and methods.
+    module CollectionRenderingHelper
+      # Renders the constants section for an object page.
+      # 
+      # _@param_ `constants` — Constant objects collected for the current page.
+      # 
+      # _@param_ `group_order` — Preferred ordering for group headings.
+      # 
+      # _@return_ — Markdown for the constants section.
+      def render_constants: (::Array[untyped] constants, ::Array[String]? group_order) -> String
+
+      # Renders the attributes section for an object page.
+      # 
+      # _@param_ `attrs` — Attributes to render.
+      # 
+      # _@param_ `group_order` — Preferred ordering for group headings.
+      # 
+      # _@return_ — Markdown for the attributes section.
+      def render_attributes: (::Array[untyped] attrs, ::Array[String]? group_order) -> String
+
+      # Renders a method section for an object page.
+      # 
+      # _@param_ `section_title` — Section title to render.
+      # 
+      # _@param_ `methods` — Method objects collected for the current section.
+      # 
+      # _@param_ `group_order` — Preferred ordering for group headings.
+      # 
+      # _@return_ — Markdown for the method section.
+      def render_methods: (String section_title, ::Array[untyped] methods, ::Array[String]? group_order) -> String
+    end
+
+    # Renders inheritance and mixin relationship summaries.
+    module RelationshipSectionHelper
+      # Returns section content with the expected trailing spacing.
+      # 
+      # _@param_ `content` — Section content to render.
+      # 
+      # _@return_ — Section content followed by blank-line spacing.
+      def render_section_content: (Object content) -> String
+
+      # Returns inheritance and mixin relationships for an object.
+      # 
+      # _@param_ `object` — Object being rendered.
+      # 
+      # _@return_ — Markdown summary of the object's relationships.
+      def object_relationships: (untyped object) -> String
+    end
   end
-end
+end

data/templates/default/fulldoc/markdown/setup.rb

@@ -1,58 +1,68 @@
 # frozen_string_literal: true
 
-# https://github.com/lsegal/yard/blob/2d197a381c5d4cc5c55b2c60fff992b31c986361/docs/CodeObjects.md
-
-require "erb"
-require "csv"
+require 'csv'
 
 include Helpers::ModuleHelper
 
+include YARD::Markdown::ArefHelper
+include YARD::Markdown::ObjectListingHelper
+
+# Prepares the markdown serializer and renders each object page.
+#
+# @return [void]
 def init
-  options.objects = objects = run_verifier(options.objects)
+  options.objects = objects = run_verifier(options.objects).reject { |item| item.name == :root }
 
   options.delete(:objects)
   options.delete(:files)
 
-  options.serializer.extension = "md"
-
-  generate_method_list
+  options.serializer.extension = 'md'
 
   objects.each do |object|
-    next if object.name == :root
-
-    begin
-      Templates::Engine.with_serializer(object, options.serializer) { serialize(object) }
-    rescue => e
-      path = options.serializer.serialized_path(object)
-      log.error "Exception occurred while generating '#{path}'"
-      log.backtrace(e)
-    end
+    Templates::Engine.with_serializer(object, options.serializer) { serialize(object) }
+  rescue StandardError => e
+    path = options.serializer.serialized_path(object)
+    log.error "Exception occurred while generating '#{path}'"
+    log.backtrace(e)
   end
 
   serialize_index(objects)
 end
 
+# Renders the markdown template for a single namespace object.
+#
+# @param object [YARD::CodeObjects::NamespaceObject] Object whose page will be serialized.
+# @return [String] Rendered markdown for the object.
+def serialize(object)
+  T('module').run(options.merge(object: object))
+end
+
+# Writes the CSV search index for all rendered objects.
+#
+# @param objects [Array<YARD::CodeObjects::NamespaceObject>] Verified objects included in the generated documentation.
+# @return [void]
 def serialize_index(objects)
   filepath = "#{options.serializer.basepath}/index.csv"
 
-  CSV.open(filepath, "wb") do |csv|
+  CSV.open(filepath, 'wb') do |csv|
     csv << %w[name type path]
 
     objects.each do |object|
       next if object.name == :root
 
       if object.type == :class
-        csv << [object.path, "Class", options.serializer.serialized_path(object)]
+        csv << [object.path, 'Class', options.serializer.serialized_path(object)]
       elsif object.type == :module
-        csv << [object.path, "Module", options.serializer.serialized_path(object)]
+        csv << [object.path, 'Module', options.serializer.serialized_path(object)]
       end
 
-      if constant_listing.size.positive?
-        constant_listing.each do |cnst|
+      constants = constant_listing(object)
+      if constants.size.positive?
+        constants.each do |cnst|
           csv << [
             "#{object.path}.#{cnst.name(false)}",
-            "Constant",
-            (options.serializer.serialized_path(object) + "#" + aref(cnst)),
+            'Constant',
+            (options.serializer.serialized_path(object) + '#' + aref(cnst))
           ]
         end
       end
@@ -61,8 +71,8 @@ def serialize_index(objects)
         insmeths.each do |item|
           csv << [
             "#{object.path}.#{item.name(false)}",
-            "Method",
-            options.serializer.serialized_path(object) + "#" + aref(item),
+            'Method',
+            options.serializer.serialized_path(object) + '#' + aref(item)
           ]
         end
       end
@@ -71,206 +81,21 @@ def serialize_index(objects)
         pubmeths.each do |item|
           csv << [
             "#{object.path}.#{item.name(false)}",
-            "Method",
-            options.serializer.serialized_path(object) + "#" + aref(item),
+            'Method',
+            options.serializer.serialized_path(object) + '#' + aref(item)
           ]
         end
       end
 
-      if (attrs = attr_listing(object)).size > 0
-        attrs.each do |item|
-          csv << [
-            item.name(false),
-            "Attribute",
-            options.serializer.serialized_path(object) + "#" + aref(item),
-          ]
-        end
-      end
-    end
-  end
-end
-
-# @param object [YARD::CodeObjects::Base]
-# @return [String] markdown formatted string
-#
-# @todo Extract template out of setup.rb class.
-def serialize(object)
-  template =
-    ERB.new(
-      '# <%= format_object_title object %>
-<% if CodeObjects::ClassObject === object && object.superclass %>
-**Inherits:** <%= object.superclass %>
-<% end %><% [[:class, "Extended by"], [:instance, "Includes"]].each do |scope, name| %>
-  <% if (mix = run_verifier(object.mixins(scope))).size > 0 %>
-**<%= name %>:** <%= mix.sort_by {|o| o.path }.join(", ") %>
-  <% end %><% end %>
-
-<%= rdoc_to_md object.docstring %>
-
-<%= render_tags object %>
-
-<% if (pubmeths = public_class_methods(object)).size > 0 %>
-# Class Methods
-<% pubmeths.each do |item| %>
-## <%= item.name(false) %>(<%= item.parameters.map {|p| p.join(" ") }.join(", ") %>) [](#<%=aref(item)%>)
-<%= rdoc_to_md item.docstring %>
-<%= render_tags item %>
-<% end %><% end %>
-<% if (attrs = attr_listing(object)).size > 0 %>
-# Attributes
-<% attrs.each do |item|%>
-## <%= item.name %><%= item.reader? ? "[RW]" : "[R]" %> [](#<%=aref(item)%>)
-<%= rdoc_to_md item.docstring %>
-
-<%= render_tags item %>
-<% end %><% end %>
-
-<% if (insmeths = public_instance_methods(object)).size > 0 %>
-# Instance Methods
-<% insmeths.each do |item| %>
-## <%= item.name(false) %>(<%= item.parameters.map {|p| p.join("") }.join(", ")%>) [](#<%=aref(item)%>)
-<%= rdoc_to_md item.docstring %>
-
-<%= render_tags item %>
-<% end %><% end %>',
-      trim_mode: "<>",
-    )
-
-  template.result(binding)
-end
-
-require "rdoc"
-
-##
-# Converts rdoc to markdown.
-#
-# I didn't found a way to detect yard/rdoc docstrings, so we're running docstrings through rdoc to markdown converter in all cases. If it's yard docstring, it doesn't seem to have any negative effect on end results. But absense of bugs, doesn't mean that there are no issues.
-#
-# @param docstring [String, YARD::Docstring]
-# @return [String] markdown formatted string
-def rdoc_to_md(docstring)
-  RDoc::Markup::ToMarkdown.new.convert(docstring)
-end
-
-##
-# Formats yard tags belonging to a object.
-#
-# This is mostly a feature of yard and rdoc doesn't have any of that. Rdoc supports ":nodoc:" and other tags. Yard claims to have full support for rdoc, doesn't really handle tags like ":nodoc:" or anything else from rdoc.
-#
-# There is an attempt to handle @example tag differently, we surround it with a code block.
-#
-# @see https://rubydoc.info/gems/yard/file/docs/TagsArch.md
-#
-# @param object [YARD::CodeObjects::Base]
-# @return [String] markdown formatted string of Tags
-
-def render_tags(object)
-  result = String.new("")
-  object.tags.each do |tag|
-    result << if !(tag.tag_name == "example")
-      "**@#{tag.tag_name}** [#{tag.types&.join(', ')}] #{tag.text}\n\n"
-    else
-      ""
-    end
-  end
-
-  object.tags.each do |tag|
-    result << if (tag.tag_name == "example")
-      "\n**@#{tag.tag_name}**\n```ruby\n#{tag.text}\n```"
-    else
-      ""
-    end
-  end
-
-  result
-end
-
-def aref(object)
-  if object.type == :constant
-    "constant-#{object.name(false)}"
-  elsif !object.attr_info.nil?
-    "attribute-#{object.scope[0]}-#{object.name(false)}"
-  else
-    "#{object.type}-#{object.scope[0]}-#{object.name(false)}"
-  end
-end
-
-def constant_listing
-  return @constants if defined?(@constants) && @constants
-
-  @constants = object.constants(included: false, inherited: false)
-  @constants += object.cvars
-  @constants
-end
+      next unless (attrs = attr_listing(object)).size > 0
 
-def public_method_list(object)
-  prune_method_listing(
-    object.meths(inherited: false, visibility: [:public]),
-    included: false,
-  ).sort_by { |m| m.name.to_s }
-end
-
-def public_class_methods(object)
-  public_method_list(object).select { |o| o.scope == :class }
-end
-
-def public_instance_methods(object)
-  public_method_list(object).select { |o| o.scope == :instance }
-end
-
-def attr_listing(object)
-  @attrs = []
-  object
-    .inheritance_tree(true)
-    .each do |superclass|
-      next if superclass.is_a?(CodeObjects::Proxy)
-      next if !options.embed_mixins.empty? && !options.embed_mixins_match?(superclass)
-      %i[class instance].each do |scope|
-        superclass.attributes[scope].each do |_name, rw|
-          attr = prune_method_listing([rw[:read], rw[:write]].compact, false).first
-          @attrs << attr if attr
-        end
+      attrs.each do |item|
+        csv << [
+          "#{object.path}.#{item.name(false)}",
+          'Attribute',
+          options.serializer.serialized_path(object) + '#' + aref(item)
+        ]
       end
-      break if options.embed_mixins.empty?
     end
-  sort_listing @attrs
-end
-
-def generate_method_list
-  @items = prune_method_listing(Registry.all(:method), false)
-  @items = @items.reject { |m| m.name.to_s =~ /=$/ && m.is_attribute? }
-  @items = @items.sort_by { |m| m.name.to_s }
-
-  # @list_title = "Method List"
-  # @list_type = "method"
-  # generate_list_contents
-  # binding.irb
-end
-
-def sort_listing(list)
-  list.sort_by { |o| [o.scope.to_s, o.name.to_s.downcase] }
-end
-
-def groups(list, type = "Method")
-  groups_data = object.groups
-  if groups_data
-    list.each { |m| groups_data |= [m.group] if m.group && owner != m.namespace }
-    others = list.select { |m| !m.group || !groups_data.include?(m.group) }
-    groups_data.each do |name|
-      items = list.select { |m| m.group == name }
-      yield(items, name) unless items.empty?
-    end
-  else
-    others = []
-    group_data = {}
-    list.each { |itm| itm.group ? (group_data[itm.group] ||= []) << itm : others << itm }
-    group_data.each { |group, items| yield(items, group) unless items.empty? }
-  end
-
-  return if others.empty?
-  if others.first.respond_to?(:scope)
-    scopes(others) { |items, scope| yield(items, "#{scope.to_s.capitalize} #{type}") }
-  else
-    yield(others, type)
   end
 end