yard-markdown 0.7.3 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8e70dddce69cb721a1297710f9737bbe477db25c0cbcccbb46b5d220c66f540d
-  data.tar.gz: d0590255cc8255a3d465ada0918e70ffca8318500da295cb09e4dc3ac0b76533
+  metadata.gz: f9d0f4cb4021498fef4a2ae549af15357c6d2fa65e2099677e75d1b25920e680
+  data.tar.gz: 465def23d344679e869e776d856ce5a694e483d46dc5ab37fcf43eebe67f11cf
 SHA512:
-  metadata.gz: 89c47649d1ea7b3d2dbc247265ed21e5c83bfb8ccfafd0420697bb9ea3fc884689923c4894018841ffe8e696cd17e62b0bb45377e88776ce35942bac3f5374b5
-  data.tar.gz: fb05c5921db78b01c28a0e34ae931eada11a890ba6c2c6d966948ac4b21bfe7ae50d7dfd6396b9a5d2f4d5507677f4da763c4668d29b665a1e0f9a34bf71e9d0
+  metadata.gz: c2c2c4b64ea40ec28ab122d2398f2cfc72823e35fbb6a50a16146b5cb5199c44df4431cd568c00917d1011812afdb6c2c4d5862eaa8a2e66a3288bb9a901b731
+  data.tar.gz: 63d188cab16ac36c3200205a01a0dd8f902061db68d2fdbc0ab81357de96cb478e44ae066e2ecd439978cba25c9ab60576aa385c0c496e32e9b3eec142de5e26

data/CHANGELOG.md

@@ -5,6 +5,10 @@ This format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
 
 ## Unreleased
 
+## 0.8.0
+
+- Adding metadata section
+
 ## 0.7.2
 
 ### Changed

data/lib/yard/markdown/metadata_section_helper.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module YARD
+  module Markdown
+    # Renders namespace metadata summaries.
+    module MetadataSectionHelper
+      # Returns inheritance, mixins, and source files for an object.
+      #
+      # @param object [YARD::CodeObjects::NamespaceObject] Object being rendered.
+      # @return [String] Markdown table containing the object's metadata.
+      def object_metadata(object)
+        rows = []
+
+        if object.instance_of?(CodeObjects::ClassObject)
+          rows << ["Inherits", metadata_reference(object.superclass)]
+        end
+
+        [[:class, "Extended by"], [:instance, "Includes"]].each do |scope, label|
+          mixins = run_verifier(object.mixins(scope)).sort_by { |item| item.path }
+          next if mixins.empty?
+
+          rows << [label, mixins.map { |mixin| metadata_reference(mixin) }.join(", ")]
+        end
+
+        files = object.files.map(&:first).uniq
+        rows << ["Defined in", files.map { |file| metadata_table_cell(file) }.join(", ")] unless files.empty?
+
+        return "" if rows.empty?
+
+        (["|  |  |", "| --- | --- |"] + rows.map { |label, value| "| **#{label}** | #{value} |" }).join("\n")
+      end
+
+      # Returns a table-safe namespace reference, linked when YARD will render it.
+      #
+      # @param target [YARD::CodeObjects::NamespaceObject, YARD::CodeObjects::Proxy] Referenced namespace.
+      # @return [String] Markdown link or plain table-cell text.
+      def metadata_reference(target)
+        label = metadata_table_cell(target.path)
+        return label unless target.is_a?(CodeObjects::Base) && run_verifier([target]).any?
+
+        "[#{label}](#{target.path})"
+      end
+
+      # Escapes text for a Markdown table cell.
+      #
+      # @param value [String] Metadata text.
+      # @return [String] GFM table-safe Markdown text.
+      def metadata_table_cell(value)
+        value.gsub(/[[:blank:]]*\R[[:blank:]]*/, " ")
+          .gsub(/[\\|]/) { |character| "\\#{character}" }
+      end
+    end
+  end
+end

data/lib/yard/markdown/section_assembly_helper.rb

@@ -4,6 +4,17 @@ module YARD
   module Markdown
     # Assembles grouped content into ordered Markdown sections.
     module SectionAssemblyHelper
+      # 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
+
       # Groups items by their YARD group and orders them for rendering.
       #
       # @param items [Array<#group>] Renderable objects that expose a YARD group name.

data/lib/yard-markdown.rb

@@ -6,9 +6,9 @@ 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/metadata_section_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"
 

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

@@ -2,7 +2,7 @@
 
 include YARD::Markdown::TagFormattingHelper,
   YARD::Markdown::SectionAssemblyHelper,
-  YARD::Markdown::RelationshipSectionHelper,
+  YARD::Markdown::MetadataSectionHelper,
   YARD::Markdown::ObjectListingHelper,
   YARD::Markdown::MethodPresentationHelper,
   YARD::Markdown::LinkNormalizationHelper,
@@ -16,7 +16,7 @@ include YARD::Markdown::TagFormattingHelper,
 # @return [void]
 def init
   sections :header,
-    :relationships,
+    :metadata,
     :docstring_section,
     :tags_section,
     :constants_section,
@@ -48,11 +48,11 @@ def header
   render_section_content(heading_with_anchors("# #{object.type.to_s.capitalize} #{object.path}", object))
 end
 
-# Renders inheritance and mixin relationships for the current object.
+# Renders metadata for the current object.
 #
-# @return [String] Markdown relationships section.
-def relationships
-  render_section_content(object_relationships(object))
+# @return [String] Markdown metadata section.
+def metadata
+  render_section_content(object_metadata(object))
 end
 
 # Renders the object's docstring as markdown.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: yard-markdown
 version: !ruby/object:Gem::Version
-  version: 0.7.3
+  version: 0.8.0
 platform: ruby
 authors:
 - Stanislav (Stas) Katkov
@@ -67,9 +67,9 @@ files:
 - lib/yard/markdown/documentation_helper.rb
 - lib/yard/markdown/heading_helper.rb
 - lib/yard/markdown/link_normalization_helper.rb
+- lib/yard/markdown/metadata_section_helper.rb
 - lib/yard/markdown/method_presentation_helper.rb
 - lib/yard/markdown/object_listing_helper.rb
-- lib/yard/markdown/relationship_section_helper.rb
 - lib/yard/markdown/section_assembly_helper.rb
 - lib/yard/markdown/tag_formatting_helper.rb
 - templates/default/fulldoc/markdown/setup.rb

data/lib/yard/markdown/relationship_section_helper.rb

@@ -1,38 +0,0 @@
-# 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