yard-markdown 0.6.0 → 0.7.1

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: (Object 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: () -> 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: (Object 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: (Object object) -> Symbol
+
+      # 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, Object 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: () -> 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: () -> 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: (Object 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: (Object object) -> Symbol
+
+      # Returns the visible public methods defined directly on an object.
+      # 
+      # _@param_ `object` — Object being rendered.
+      # 
+      # _@return_ — Sorted public methods.
+      def public_method_list: (Object object) -> Symbol
+
+      # Returns the public class methods defined directly on an object.
+      # 
+      # _@param_ `object` — Object being rendered.
+      # 
+      # _@return_ — Sorted public class methods.
+      def public_class_methods: (Object object) -> Symbol
+
+      # Returns the public instance methods defined directly on an object.
+      # 
+      # _@param_ `object` — Object being rendered.
+      # 
+      # _@return_ — Sorted public instance methods.
+      def public_instance_methods: (Object object) -> Symbol
+
+      # Returns the visible attribute methods for an object.
+      # 
+      # _@param_ `object` — Object being rendered.
+      # 
+      # _@return_ — Sorted attribute methods.
+      def attr_listing: (Object object) -> Symbol
+
+      # Sorts a listing by scope and case-insensitive name.
+      # 
+      # _@param_ `list` — Objects to sort.
+      # 
+      # _@return_ — Sorted objects.
+      def sort_listing: (Symbol list) -> Symbol
+
+      # 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?: (Object 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: (Object 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: (Object tag) -> String
+
+      # Normalizes tag type declarations into printable strings.
+      # 
+      # _@param_ `types` — Raw tag types from YARD.
+      # 
+      # _@return_ — Cleaned type strings.
+      def normalized_tag_types: (Symbol? types) -> Symbol
+
+      # 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: (Symbol items, Symbol? group_order) -> Symbol
+
+      # 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: (Symbol 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 | Symbol) 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) -> Object?
+
+      # 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: (Object method_object) -> String
+
+      # Returns the rendered parameter list for a method.
+      # 
+      # _@param_ `method_object` — Method being rendered.
+      # 
+      # _@return_ — Parenthesized method signature.
+      def method_signature: (Object 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: (Object 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: (Symbol constants, Symbol? 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: (Symbol attrs, Symbol? 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, Symbol methods, Symbol? 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: (Object object) -> String
+    end
   end
-end
+end

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

@@ -1,20 +1,27 @@
 # frozen_string_literal: true
 
-require 'csv'
+require "csv"
 
-include Helpers::ModuleHelper
+class_eval do
+  include YARD::Templates::Helpers::ModuleHelper
+  include YARD::Markdown::ArefHelper
+  include YARD::Markdown::ObjectListingHelper
+end
 
+# Prepares the markdown serializer and renders each object page.
+#
+# @return [void]
 def init
   options.objects = objects = run_verifier(options.objects).reject { |item| item.name == :root }
 
   options.delete(:objects)
   options.delete(:files)
 
-  options.serializer.extension = 'md'
+  options.serializer.extension = "md"
 
   objects.each do |object|
     Templates::Engine.with_serializer(object, options.serializer) { serialize(object) }
-  rescue StandardError => e
+  rescue => e
     path = options.serializer.serialized_path(object)
     log.error "Exception occurred while generating '#{path}'"
     log.backtrace(e)
@@ -23,23 +30,31 @@ def init
   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))
+  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
 
       constants = constant_listing(object)
@@ -47,8 +62,8 @@ def serialize_index(objects)
         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
@@ -57,8 +72,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
@@ -67,8 +82,8 @@ 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
@@ -78,79 +93,10 @@ def serialize_index(objects)
       attrs.each do |item|
         csv << [
           "#{object.path}.#{item.name(false)}",
-          'Attribute',
-          options.serializer.serialized_path(object) + '#' + aref(item)
+          "Attribute",
+          options.serializer.serialized_path(object) + "#" + aref(item)
         ]
       end
     end
   end
 end
-
-def aref(object)
-  type = object.type
-
-  return "class-#{anchor_component(object.path.gsub('::', '-'))}" if type == :class
-  return "module-#{anchor_component(object.path.gsub('::', '-'))}" if type == :module
-  return "constant-#{anchor_component(object.name(false))}" if type == :constant
-  return "classvariable-#{anchor_component(object.name(false))}" if type == :classvariable
-
-  scope = object.scope == :class ? 'c' : 'i'
-
-  if object.respond_to?(:attr_info) && !object.attr_info.nil?
-    "attribute-#{scope}-#{anchor_component(object.name(false))}"
-  else
-    "method-#{scope}-#{anchor_component(object.name(false))}"
-  end
-end
-
-def anchor_component(value)
-  value.to_s.each_char.map do |char|
-    char.match?(/[A-Za-z0-9_-]/) ? char : format('-%X', char.ord)
-  end.join
-end
-
-def constant_listing(object)
-  constants = object.constants(included: false, inherited: false)
-  constants + object.cvars
-end
-
-def public_method_list(object)
-  prune_method_listing(
-    object.meths(inherited: false, visibility: [:public]),
-    included: false
-  ).reject { |item| hidden_object?(item) }
-    .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
-    end
-    break if options.embed_mixins.empty?
-  end
-  sort_listing(attrs)
-end
-
-def sort_listing(list)
-  list.sort_by { |o| [o.scope.to_s, o.name.to_s.downcase] }
-end
-
-def hidden_object?(object)
-  object.docstring.to_s.strip.start_with?(':nodoc:')
-end