yard-markdown 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f9d0f4cb4021498fef4a2ae549af15357c6d2fa65e2099677e75d1b25920e680
-  data.tar.gz: 465def23d344679e869e776d856ce5a694e483d46dc5ab37fcf43eebe67f11cf
+  metadata.gz: 756196562ff8a2cafba54128de039d2f10fffd93816a9fc0abdad8130805e124
+  data.tar.gz: 3a6f3bdfd92a9a95e632dac284f33151e89c26a1be283deac463f600971774a6
 SHA512:
-  metadata.gz: c2c2c4b64ea40ec28ab122d2398f2cfc72823e35fbb6a50a16146b5cb5199c44df4431cd568c00917d1011812afdb6c2c4d5862eaa8a2e66a3288bb9a901b731
-  data.tar.gz: 63d188cab16ac36c3200205a01a0dd8f902061db68d2fdbc0ab81357de96cb478e44ae066e2ecd439978cba25c9ab60576aa385c0c496e32e9b3eec142de5e26
+  metadata.gz: 04ea8878df7097ebf384ae8c45110c01036af65ce2004710c3f0c40fc20eb4cc8ccabec5f0dd4877c5abbf8c3305f7b42caa66581c4f884848b389d9106218d8
+  data.tar.gz: ef8e21cb4d98c319f37eab85291ecd69e808c3c074909adee7376d0fb7ab79e3d62436d86b082c69ef6777fa1eb7706ce9088cd39d648e8fe53fa00daa1ee7f7

data/CHANGELOG.md

@@ -5,6 +5,10 @@ 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

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

@@ -36,7 +36,7 @@ module YARD
       # @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?
+        return label unless target.is_a?(CodeObjects::NamespaceObject) && run_verifier([target]).any?
 
         "[#{label}](#{target.path})"
       end

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,6 +1,7 @@
 # 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"
@@ -11,10 +12,7 @@ require_relative "yard/markdown/method_presentation_helper"
 require_relative "yard/markdown/object_listing_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
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: yard-markdown
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.9.0
 platform: ruby
 authors:
 - Stanislav (Stas) Katkov
@@ -62,6 +62,7 @@ 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
@@ -72,6 +73,7 @@ files:
 - lib/yard/markdown/object_listing_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