yard-markdown 0.7.3 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8e70dddce69cb721a1297710f9737bbe477db25c0cbcccbb46b5d220c66f540d
-  data.tar.gz: d0590255cc8255a3d465ada0918e70ffca8318500da295cb09e4dc3ac0b76533
+  metadata.gz: 756196562ff8a2cafba54128de039d2f10fffd93816a9fc0abdad8130805e124
+  data.tar.gz: 3a6f3bdfd92a9a95e632dac284f33151e89c26a1be283deac463f600971774a6
 SHA512:
-  metadata.gz: 89c47649d1ea7b3d2dbc247265ed21e5c83bfb8ccfafd0420697bb9ea3fc884689923c4894018841ffe8e696cd17e62b0bb45377e88776ce35942bac3f5374b5
-  data.tar.gz: fb05c5921db78b01c28a0e34ae931eada11a890ba6c2c6d966948ac4b21bfe7ae50d7dfd6396b9a5d2f4d5507677f4da763c4668d29b665a1e0f9a34bf71e9d0
+  metadata.gz: 04ea8878df7097ebf384ae8c45110c01036af65ce2004710c3f0c40fc20eb4cc8ccabec5f0dd4877c5abbf8c3305f7b42caa66581c4f884848b389d9106218d8
+  data.tar.gz: ef8e21cb4d98c319f37eab85291ecd69e808c3c074909adee7376d0fb7ab79e3d62436d86b082c69ef6777fa1eb7706ce9088cd39d648e8fe53fa00daa1ee7f7

data/CHANGELOG.md

@@ -5,6 +5,14 @@ This format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
 
 ## Unreleased
 
+## 0.9.0
+
+- Detect Markdown files, copy them into generated documentation, and include them in `index.csv`.
+
+## 0.8.0
+
+- Adding metadata section
+
 ## 0.7.2
 
 ### Changed

data/README.md

@@ -19,6 +19,20 @@ gem install yard-markdown
 
 Run `yardoc --format=markdown` to generate markdown documentation.
 
+Markdown files in the project tree are detected automatically, copied unchanged into the output, and listed in `index.csv`:
+
+```bash
+yardoc --format=markdown
+```
+
+Markdown files whose basename starts with `_` are ignored automatically.
+
+Use YARD's `--exclude` option to omit a separate documentation tree:
+
+```bash
+yardoc --format=markdown --exclude '\Adocs/'
+```
+
 ## FAQ
 
 ### Note on RDoc support
@@ -66,14 +80,14 @@ Validate generated markdown in sample docs:
 bundle exec rake markdown:validate_examples
 ```
 
-There is also a real-world validation harness for repositories with substantial YARD documentation (`rspec-core`, `sidekiq`):
+There is also a real-world validation harness for repositories with substantial YARD documentation (`faraday`, `sidekiq`):
 
 ```bash
 bundle exec rake markdown:validate_real_world
 ```
 
-This task validates generated markdown against CommonMark + GFM rendering, and reports unresolved local links found in upstream source comments while still validating local anchor/link structure.
+This task validates every generated Markdown file against CommonMark and GFM. Generated files must have valid local links and anchors; unresolved links and anchors in byte-identical Markdown copied from upstream are reported instead of failing validation.
 
-GitHub Actions CI now runs this task on every push/PR, so `sidekiq` and other real-world fixture gems are verified continuously.
+GitHub Actions CI runs this task on every push/PR, so both real-world fixture gems are verified continuously.
 
-For reproducible checks, the task clones pinned tags (`rspec-core` `v3.13.2`, `sidekiq` `v7.3.10`) into `tmp/real-world/repos` before generating output.
+For reproducible checks, the task clones pinned tags (`faraday` `v2.14.3`, `sidekiq` `v7.3.10`) into `tmp/real-world/repos` and honors each repository's `.yardopts` before generating output in `tmp/real-world/faraday` and `tmp/real-world/sidekiq`.

data/lib/yard/markdown/link_normalization_helper.rb

@@ -13,7 +13,6 @@ module YARD
         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
@@ -83,12 +82,16 @@ module YARD
           return relative_output_path(current_dir, object_path)
         end
 
+        alias_path = Pathname.new(normalized.sub(/\.html\z/i, "")).cleanpath.to_s
+        copied_path = options.copied_file_aliases[alias_path]
+        return relative_output_path(current_dir, copied_path) if copied_path
+
         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?("/")
+          normalized = "#{normalized}.md"
         end
 
         relative_output_path(current_dir, normalized)
@@ -111,9 +114,7 @@ module YARD
       # @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/)
+        File.extname(cleaned).empty? && !cleaned.include?("/")
       end
 
       # Computes a relative path from the current output directory.
@@ -129,14 +130,6 @@ module YARD
       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/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::NamespaceObject) && 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/yardoc_extension.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module YARD
+  module Markdown
+    # Discovers Markdown pages before YARD generates documentation.
+    module YardocExtension
+      private
+
+      # Adds Markdown pages to the files rendered by the Markdown template.
+      #
+      # @param checksums [Hash, nil] Previously generated file checksums.
+      # @return [void]
+      def run_generate(checksums)
+        if options.format == :markdown
+          existing = options.files.map { |file| File.expand_path(file.filename) }
+          exclusions = excluded.map { |path| Regexp.new(path, Regexp::IGNORECASE) }
+          output = File.expand_path(options.serializer.basepath)
+          markdown_files = Dir.glob("**/*").grep(FILE_PATTERN)
+            .reject { |file| File.basename(file).start_with?("_") }
+            .reject { |file| exclusions.any? { |pattern| pattern.match?(file) } }
+            .reject { |file| File.expand_path(file).start_with?("#{output}/") }
+            .reject { |file| existing.include?(File.expand_path(file)) }
+          add_extra_files(markdown_files)
+        end
+
+        super
+      end
+    end
+  end
+end

data/lib/yard/markdown.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module YARD
+  module Markdown
+    # Matches supported Markdown file extensions.
+    FILE_PATTERN = /\.(?:md|markdown)\z/i
+  end
+end

data/lib/yard-markdown.rb

@@ -1,20 +1,18 @@
 # frozen_string_literal: true
 
 require "yard"
+require_relative "yard/markdown"
 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/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"
-
-module YARD
-  module Markdown
-  end
-end
+require_relative "yard/markdown/yardoc_extension"
 
 YARD::Templates::Engine.register_template_path File.dirname(__FILE__) + "/../templates"
+YARD::CLI::Yardoc.prepend(YARD::Markdown::YardocExtension)

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

@@ -11,12 +11,19 @@ include YARD::Markdown::ObjectListingHelper,
 # @return [void]
 def init
   options.objects = objects = run_verifier(options.objects).reject { |item| item.name == :root }
+  files = Array(options.files).select { |file| file.filename.match?(YARD::Markdown::FILE_PATTERN) }
+  options.copied_file_aliases = files.to_h do |file|
+    path = Pathname.new(file.filename).cleanpath.to_s
+    [path.sub(YARD::Markdown::FILE_PATTERN, ""), path]
+  end
 
   options.delete(:objects)
   options.delete(:files)
 
   options.serializer.extension = "md"
 
+  files.each { |file| options.serializer.serialize(file.filename, File.binread(file.filename)) }
+
   objects.each do |object|
     Templates::Engine.with_serializer(object, options.serializer) { serialize(object) }
   rescue => e
@@ -25,7 +32,7 @@ def init
     log.backtrace(e)
   end
 
-  serialize_index(objects)
+  serialize_index(objects, files)
 end
 
 # Renders the markdown template for a single namespace object.
@@ -39,13 +46,16 @@ end
 # Writes the CSV search index for all rendered objects.
 #
 # @param objects [Array<YARD::CodeObjects::NamespaceObject>] Verified objects included in the generated documentation.
+# @param files [Array<YARD::CodeObjects::ExtraFileObject>] Markdown files included in the generated documentation.
 # @return [void]
-def serialize_index(objects)
+def serialize_index(objects, files)
   filepath = "#{options.serializer.basepath}/index.csv"
 
   CSV.open(filepath, "wb") do |csv|
     csv << %w[name type path]
 
+    files.each { |file| csv << [file.title, "File", file.filename] }
+
     objects.each do |object|
       next if object.name == :root
 

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.9.0
 platform: ruby
 authors:
 - Stanislav (Stas) Katkov
@@ -62,16 +62,18 @@ files:
 - LICENSE.txt
 - README.md
 - lib/yard-markdown.rb
+- lib/yard/markdown.rb
 - lib/yard/markdown/aref_helper.rb
 - lib/yard/markdown/collection_rendering_helper.rb
 - 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
+- lib/yard/markdown/yardoc_extension.rb
 - templates/default/fulldoc/markdown/setup.rb
 - templates/default/module/markdown/setup.rb
 homepage: https://poshtui.com

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