yard-markdown 0.7.0 → 0.7.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 41e14595e84affb837da2c36afb9a40f0e7ea866472fa32e5aefabc7c32c2ec8
-  data.tar.gz: 605f1ad9c9496ebaf48afc7245ab25db98b5e22aed88c7c718bb3968f78b3b5e
+  metadata.gz: 6aa034296e039353941780b9556959dabbddad7874f52231b0dc69faed55b662
+  data.tar.gz: 379509fb60bb677e34f4ef90e3d6776462a6f9d0768fcf09c078866c78967476
 SHA512:
-  metadata.gz: '0887584b2fe63298271fad1483237eb303d215068a6da79aee7cb59c463a6c2838a6a72171676e7876f7a7d8c9003c0e23eb0fcb9dbfd88e329f028c5907bdef'
-  data.tar.gz: 9d50e908447b65b564315c996af01a43e35d360f2bafd600d34197ed20fc0cf8fde1b506850eb2fd476ee65d33c44ff10de8658abcd51037011060d4e69ec59f
+  metadata.gz: 7a93025d200cc5711781fefced38b4e2a4e91ca6fb7228b744c28c1c8dfae8b18819b12bfcec1c7b9b6051c4f179342d55b8bd3bdf07ec083ea9e36ca60f59c7
+  data.tar.gz: f25532bd94b48553decf5b8c1a48c9bc92dcf639aadfc09b02a6c8ec77f8a9c568515d21991b891499d76643f4ab42c0e4df19d6e0588df887480734b756a7d9

data/CHANGELOG.md

@@ -5,6 +5,19 @@ This format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
 
 ## Unreleased
 
+## 0.7.2
+
+### Changed
+- Limit the packaged gem to documentation, runtime code, and templates.
+
+### Removed
+- Remove the generated RBS signature from the packaged gem.
+
+## 0.7.1
+
+### Fixed
+- Preserve fenced code blocks in YARD docstrings so generated Markdown examples render correctly.
+
 ## 0.7.0
 ## Added
 - Adding yard-lint and all method documentation
@@ -14,4 +27,3 @@ This format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
 ## Changed
 - Refactoring and simplification of teamplate, mostly driven by mutantion testing
 - Improve documentation for entire project
-

data/README.md

@@ -12,15 +12,6 @@ It's a pitty that rdoc and yard can't output a proper markdown file. I would lik
 - Mimick yard html layout where it makes sense to maintain familiarity
 
 ## Usage
-Yard doesn't load plugin by default, so you need to load plugin through `~/.yard/config`:
-
-```yaml
-!!!yaml
-load_plugins: true
-autoload_plugins:
-  - markdown
-```
-
 Install a plugin
 ```
 gem install yard-markdown
@@ -28,20 +19,32 @@ gem install yard-markdown
 
 Run `yardoc --format=markdown` to generate markdown documentation.
 
-## Note on RDoc support
+## FAQ
+
+### Note on RDoc support
 It seems important to note, that yard claims to have support for RDoc. That support is certainly present, but output for rdoc is dramatically different. A lot of useful information seems lost in the process.
 
 If you know how to improve that, please get in touch or submit a patch.
 
 So in meantime, there is work going on a competing gem for RDoc and it's called [rdoc-markdown gem](https://github.com/skatkov/rdoc-markdown/).
 
-## Note on index.csv file
+### Note on index.csv file
 This gem emits index of all markdown files in a index.csv file.
 
 There are decent tools that offer search through structured plain-text files. But my expectation is that nobody will use CSV as an actual search index, but rather import it into something that performs this function better.
 
 In my personal use-case, I use SQLite. All other databases seem to have a good support for CSV imports.
 
+### Yard doesn't load plugin properly? 
+so you need to load plugin through `~/.yard/config`:
+
+```yaml
+!!!yaml
+load_plugins: true
+autoload_plugins:
+  - markdown
+```
+
 ## Testing
 Unit tests verify renderer behavior, index links, and anchor consistency for both YARD-style and RDoc-style sources.
 
@@ -63,12 +66,6 @@ Validate generated markdown in sample docs:
 bundle exec rake markdown:validate_examples
 ```
 
-Regenerate the checked-in RBS types derived from YARD docs:
-
-```bash
-bundle exec rake types:generate
-```
-
 There is also a real-world validation harness for repositories with substantial YARD documentation (`rspec-core`, `sidekiq`):
 
 ```bash
@@ -79,6 +76,4 @@ This task validates generated markdown against CommonMark + GFM rendering, and r
 
 GitHub Actions CI now runs this task on every push/PR, so `sidekiq` and other real-world fixture gems are verified continuously.
 
-CI also regenerates `sig/yard/markdown.rbs` with `sord` and fails if the checked-in RBS file is out of date.
-
 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.

data/lib/yard/markdown/aref_helper.rb

@@ -1,10 +1,20 @@
 # frozen_string_literal: true
 
+# Namespace for YARD extensions used by this gem.
 module YARD
+  # Shared helpers for rendering YARD objects as Markdown.
   module Markdown
     # Computes anchor ids that match the generated Markdown headings.
     module ArefHelper
-      include AnchorComponentHelper
+      # Encodes a value so it can be embedded safely in an HTML anchor id.
+      #
+      # @param value [Object] Raw anchor fragment to encode.
+      # @return [String] Anchor-safe identifier fragment.
+      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
 
       # Returns the primary anchor id for a documented object.
       #
@@ -13,12 +23,12 @@ module YARD
       def aref(object)
         type = object.type
 
-        return "class-#{object.path.gsub('::', '-')}" if type == :class
-        return "module-#{object.path.gsub('::', '-')}" if type == :module
+        return "class-#{object.path.gsub("::", "-")}" if type == :class
+        return "module-#{object.path.gsub("::", "-")}" if type == :module
         return "constant-#{object.name}" if type == :constant
         return "classvariable-#{anchor_component(object.name)}" if type == :classvariable
 
-        scope = object.scope == :class ? 'c' : 'i'
+        scope = (object.scope == :class) ? "c" : "i"
 
         if !object.attr_info.nil?
           "attribute-#{scope}-#{object.name}"

data/lib/yard/markdown/collection_rendering_helper.rb

@@ -10,27 +10,7 @@ module YARD
       # @param group_order [Array<String>, nil] Preferred ordering for group headings.
       # @return [String] Markdown for the constants section.
       def render_constants(constants, group_order)
-        lines = ['## Constants']
-        grouped_constants = grouped_items(constants.sort_by { |item| item.name }, group_order)
-        uses_groups = grouped_constants.any? { |name, _items| !name.nil? }
-
-        grouped_constants.each do |group_name, items|
-          if uses_groups
-            lines << "### #{group_name || 'General'}"
-            item_heading = '####'
-          else
-            item_heading = '###'
-          end
-
-          lines << items.map { |item|
-            item_lines = [heading_with_anchors("#{item_heading} `#{item.name}`", item)]
-            append_lines(item_lines, documented_text(item), separated: false)
-            append_lines(item_lines, render_tags(item), separated: false)
-            item_lines.join("\n")
-          }.join("\n\n")
-        end
-
-        lines.join("\n")
+        render_collection("Constants", constants.sort_by { |item| item.name }, group_order) { |item| "`#{item.name}`" }
       end
 
       # Renders the attributes section for an object page.
@@ -39,27 +19,7 @@ module YARD
       # @param group_order [Array<String>, nil] Preferred ordering for group headings.
       # @return [String] Markdown for the attributes section.
       def render_attributes(attrs, group_order)
-        lines = ['## Attributes']
-        grouped_attrs = grouped_items(attrs, group_order)
-        uses_groups = grouped_attrs.any? { |name, _items| !name.nil? }
-
-        grouped_attrs.each do |group_name, items|
-          if uses_groups
-            lines << "### #{group_name || 'General'}"
-            item_heading = '####'
-          else
-            item_heading = '###'
-          end
-
-          lines << items.map { |item|
-            item_lines = [heading_with_anchors("#{item_heading} `#{item.name}` [#{attribute_access(item)}]", item)]
-            append_lines(item_lines, documented_text(item), separated: false)
-            append_lines(item_lines, render_tags(item), separated: false)
-            item_lines.join("\n")
-          }.join("\n\n")
-        end
-
-        lines.join("\n")
+        render_collection("Attributes", attrs, group_order) { |item| "`#{item.name}` [#{attribute_access(item)}]" }
       end
 
       # Renders a method section for an object page.
@@ -69,20 +29,26 @@ module YARD
       # @param group_order [Array<String>, nil] Preferred ordering for group headings.
       # @return [String] Markdown for the method section.
       def render_methods(section_title, methods, group_order)
+        render_collection(section_title, methods, group_order) { |item| "`#{formatted_method_heading(item)}`" }
+      end
+
+      # Renders a grouped collection with a caller-provided item label.
+      #
+      # @param section_title [String] Section title to render.
+      # @param items [Array<YARD::CodeObjects::Base>] Objects to group and render.
+      # @param group_order [Array<String>, nil] Preferred ordering for group headings.
+      # @return [String] Markdown for the collection section.
+      def render_collection(section_title, items, group_order)
         lines = ["## #{section_title}"]
-        grouped_methods = grouped_items(methods, group_order)
-        uses_groups = grouped_methods.any? { |name, _items| !name.nil? }
+        groups = grouped_items(items, group_order)
+        uses_groups = groups.any? { |name, _items| !name.nil? }
+        item_heading = uses_groups ? "####" : "###"
 
-        grouped_methods.each do |group_name, items|
-          if uses_groups
-            lines << "### #{group_name || 'General'}"
-            item_heading = '####'
-          else
-            item_heading = '###'
-          end
+        groups.each do |group_name, group_items|
+          lines << "### #{group_name || "General"}" if uses_groups
 
-          lines << items.map { |item|
-            item_lines = [heading_with_anchors("#{item_heading} `#{formatted_method_heading(item)}`", item)]
+          lines << group_items.map { |item|
+            item_lines = [heading_with_anchors("#{item_heading} #{yield(item)}", item)]
             append_lines(item_lines, documented_text(item), separated: false)
             append_lines(item_lines, render_tags(item), separated: false)
             item_lines.join("\n")

data/lib/yard/markdown/documentation_helper.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require 'rdoc'
+require "rdoc"
 
 module YARD
   module Markdown
@@ -13,9 +13,9 @@ module YARD
       def documented_text(object)
         text = rdoc_to_md(object.docstring)
         return text unless text.empty?
-        return '' unless object.tags.empty?
+        return "" unless object.tags.empty?
 
-        'Not documented.'
+        "Not documented."
       end
 
       # Converts an RDoc-formatted docstring to Markdown.
@@ -23,7 +23,19 @@ module YARD
       # @param docstring [Object] Raw docstring content.
       # @return [String] Markdown-rendered docstring content.
       def rdoc_to_md(docstring)
-        RDoc::Markup::ToMarkdown.new.convert(docstring).rstrip
+        fenced_code_blocks = []
+        placeholder = "YARD_MARKDOWN_FENCED_CODE_BLOCK_%d"
+        content = docstring.gsub(/^```[^\n]*\n.*?^```[ \t]*$/m) do |block|
+          fenced_code_blocks << block
+          format(placeholder, fenced_code_blocks.length - 1)
+        end
+
+        markdown = RDoc::Markup::ToMarkdown.new.convert(content).rstrip
+        fenced_code_blocks.each_with_index do |block, index|
+          markdown = markdown.sub(format(placeholder, index), block)
+        end
+
+        markdown
       end
     end
   end

data/lib/yard/markdown/heading_helper.rb

@@ -37,7 +37,7 @@ module YARD
       # @param object [YARD::CodeObjects::Base] Object being rendered.
       # @return [String] Heading text with embedded anchor tags.
       def heading_with_anchors(heading, object)
-        "#{heading} #{anchor_tags_for(object).join(' ')}"
+        "#{heading} #{anchor_tags_for(object).join(" ")}"
       end
 
       # Builds an HTML anchor tag for a generated id.

data/lib/yard/markdown/link_normalization_helper.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require 'pathname'
-
 module YARD
   module Markdown
     # Rewrites generated Markdown links so they point at Markdown output.
@@ -31,12 +29,12 @@ module YARD
         markdown.gsub(%r{\[(.+?)\]\((?!https?://|mailto:|#)([^)\n]+)\)}) do
           label = Regexp.last_match(1)
           target = Regexp.last_match(2)
-          path = target.sub(/[?#].*\z/, '')
+          path = target.sub(/[?#].*\z/, "")
           suffix = target[path.length..]
           rewritten_path = resolve_local_link_target(path, current_dir)
 
           if rewritten_path.nil?
-            "`#{label.tr('`', '')}`"
+            "`#{label.tr("`", "")}`"
           else
             "[#{label}](#{rewritten_path}#{suffix})"
           end
@@ -49,15 +47,15 @@ module YARD
       # @param current_dir [Pathname] Directory for the current output file.
       # @return [YARD::CodeObjects::Base, nil] Matched registry object, if any.
       def resolve_registry_object(path, current_dir)
-        cleaned = path.sub(%r{\A(?:(?:\.\./)+|\./)}, '')
+        cleaned = path.sub(%r{\A(?:(?:\.\./)+|\./)}, "")
         candidates = [path]
 
         if constant_reference_path?(cleaned)
-          current_parts = current_dir.to_s.split('/').reject { |part| part.empty? || part == '.' }
-          target_parts = cleaned.split('/')
+          current_parts = current_dir.to_s.split("/").reject { |part| part.empty? || part == "." }
+          target_parts = cleaned.split("/")
 
           current_parts.length.downto(0) do |depth|
-            candidates << (current_parts.first(depth) + target_parts).join('::')
+            candidates << (current_parts.first(depth) + target_parts).join("::")
           end
         end
 
@@ -77,7 +75,7 @@ module YARD
       # @param current_dir [Pathname] Directory for the current output file.
       # @return [String, nil] Relative Markdown path, or nil when unresolved.
       def resolve_local_link_target(path, current_dir)
-        normalized = path.sub(%r{\A/+}, '')
+        normalized = path.sub(%r{\A/+}, "")
 
         obj = resolve_registry_object(normalized, current_dir)
         if obj
@@ -86,11 +84,11 @@ module YARD
         end
 
         if normalized.match?(/\.html\z/i)
-          normalized = normalized.sub(/\.html\z/i, '.md')
+          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" if normalized.include?("/")
         end
 
         relative_output_path(current_dir, normalized)
@@ -112,8 +110,8 @@ module YARD
       # @param path [String] Link target to inspect.
       # @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 = path.sub(%r{\A(?:(?:\.\./)+|\./)}, "")
+        return true if cleaned.start_with?(":") || cleaned.match?(/\A\d/)
 
         cleaned.match?(/\A[a-z_]\w*\z/)
       end
@@ -125,10 +123,10 @@ module YARD
       # @return [String] Relative path suitable for a Markdown link.
       def relative_output_path(current_dir, target_path)
         target = target_path.to_s
-        return target if target.start_with?('../')
+        return target if target.start_with?("../")
 
         Pathname.new(target).relative_path_from(current_dir).to_s
-      rescue StandardError
+      rescue
         target
       end
 

data/lib/yard/markdown/method_presentation_helper.rb

@@ -11,7 +11,7 @@ module YARD
       def formatted_method_heading(method_object)
         name = method_object.name
         signature = method_signature(method_object)
-        signature = " #{signature}" if name.end_with?(']')
+        signature = " #{signature}" if name.end_with?("]")
         "#{name}#{signature}"
       end
 
@@ -20,13 +20,13 @@ module YARD
       # @param method_object [YARD::CodeObjects::MethodObject] Method being rendered.
       # @return [String] Parenthesized method signature.
       def method_signature(method_object)
-        return '()' if method_object.parameters.nil?
+        return "()" if method_object.parameters.nil?
 
         rendered = method_object.parameters.map do |name, default|
-          default.nil? || default.empty? ? name : "#{name} = #{default}"
+          (default.nil? || default.empty?) ? name : "#{name} = #{default}"
         end
 
-        "(#{rendered.join(', ')})"
+        "(#{rendered.join(", ")})"
       end
 
       # Returns the access marker for an attribute.
@@ -34,15 +34,11 @@ module YARD
       # @param attribute [YARD::CodeObjects::MethodObject] Attribute reader or writer.
       # @return [String] Access mode marker such as `R`, `W`, or `RW`.
       def attribute_access(attribute)
-        info = attribute.attr_info || {}
-        return 'RW' if info[:read] && info[:write]
-        return 'R' if info[:read]
-        return 'W' if info[:write]
+        read, write = attribute.attr_info.fetch_values(:read, :write)
+        return "RW" if read && write
+        return "R" if read
 
-        return 'RW' if attribute.reader? && attribute.writer?
-        return 'R' if attribute.reader?
-
-        'W'
+        "W"
       end
     end
   end

data/lib/yard/markdown/object_listing_helper.rb

@@ -80,7 +80,7 @@ module YARD
       # @param object [YARD::CodeObjects::Base] Listed object whose docstring may start with `:nodoc:`.
       # @return [Boolean] True when the object should be hidden.
       def hidden_object?(object)
-        object.docstring.lstrip.start_with?(':nodoc:')
+        object.docstring.start_with?(":nodoc:")
       end
     end
   end

data/lib/yard/markdown/relationship_section_helper.rb

@@ -10,7 +10,7 @@ module YARD
       # @return [String] Section content followed by blank-line spacing.
       def render_section_content(content)
         text = content.to_s.strip
-        return '' if text.empty?
+        return "" if text.empty?
 
         "#{text}\n\n"
       end
@@ -24,11 +24,11 @@ module YARD
 
         lines << "**Inherits:** `#{object.superclass}`" if object.instance_of?(CodeObjects::ClassObject)
 
-        [[:class, 'Extended by'], [:instance, 'Includes']].each do |scope, label|
+        [[: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(', ')}"
+          lines << "**#{label}:** #{mixins.map { |mixin| "`#{mixin.path}`" }.join(", ")}"
         end
 
         lines.join("\n")

data/lib/yard/markdown/section_assembly_helper.rb

@@ -10,23 +10,12 @@ module YARD
       # @param group_order [Array<String>, nil] Preferred ordering for named groups.
       # @return [Array<Array>] Ordered pairs of group names and grouped items.
       def grouped_items(items, group_order)
-        grouped = Hash.new { |hash, key| hash[key] = [] }
-        items.each { |item| grouped[item.group] << item }
+        groups = items.group_by(&:group)
+        names = groups.keys
+        order = Array(group_order)
+        ordered_names = (order & names) + (names.compact - order).sort + ([nil] & names)
 
-        ordered = []
-
-        Array(group_order).each do |name|
-          next unless grouped.key?(name)
-
-          ordered << [name, grouped.delete(name)]
-        end
-
-        grouped.keys.compact.sort.each do |name|
-          ordered << [name, grouped.delete(name)]
-        end
-
-        ordered << [nil, grouped.delete(nil)] if grouped.key?(nil)
-        ordered
+        ordered_names.map { |name| [name, groups.fetch(name)] }
       end
 
       # Appends non-empty content to a mutable list of lines.
@@ -38,7 +27,7 @@ module YARD
       def append_lines(lines, content, separated: true)
         return if content.lstrip.empty?
 
-        lines << '' if separated && !lines.empty? && !lines.last.empty?
+        lines << "" if separated && !lines.empty? && !lines.last.empty?
         lines.concat(content.split("\n"))
       end
     end

data/lib/yard/markdown/tag_formatting_helper.rb

@@ -9,21 +9,16 @@ module YARD
       # @param object [YARD::CodeObjects::Base] Object whose tags are being rendered.
       # @return [String] Markdown representation of the object's tags.
       def render_tags(object)
-        lines = []
-        regular_tags = object.tags.reject { |tag| tag.tag_name == 'example' }
-        example_tags = object.tags.select { |tag| tag.tag_name == 'example' }
-
-        regular_tags.each do |tag|
-          lines << "- #{format_tag(tag)}"
-        end
+        example_tags, regular_tags = object.tags.partition { |tag| tag.tag_name == "example" }
+        lines = regular_tags.map { |tag| "- #{format_tag(tag)}" }
 
         example_tags.each do |tag|
           lines << nil unless lines.empty?
-          title = tag.name.to_s.rstrip.empty? ? '**@example**' : "**@example #{tag.name}**"
+          title = tag.name.to_s.rstrip.empty? ? "**@example**" : "**@example #{tag.name}**"
           lines << title
-          lines << '```ruby'
+          lines << "```ruby"
           lines << tag.text.to_s.rstrip
-          lines << '```'
+          lines << "```"
         end
 
         lines.join("\n")
@@ -38,37 +33,18 @@ module YARD
         parts << "`#{tag.name}`" unless tag.name.to_s.lstrip.empty?
 
         cleaned_types = normalized_tag_types(tag.types)
-        parts << "[#{cleaned_types.join(', ')}]" unless cleaned_types.empty?
+        parts << "[#{cleaned_types.join(", ")}]" unless cleaned_types.empty?
         parts << tag.text.strip unless tag.text.to_s.lstrip.empty?
 
-        parts.join(' ')
+        parts.join(" ")
       end
 
       # Normalizes tag type declarations into printable strings.
       #
-      # @param types [Array<Object>, Hash, nil] Raw tag types from YARD.
+      # @param types [Array<Object>, nil] Raw tag types from YARD.
       # @return [Array<String>] Cleaned type strings.
       def normalized_tag_types(types)
-        values = if types.instance_of?(Hash)
-                   types.map { |name, value| format_hash_tag_type(name, value) }
-                 else
-                   Array(types)
-                 end
-
-        values.map(&:to_s).map(&:strip).reject(&:empty?)
-      end
-
-      # Formats a hash-style tag type entry.
-      #
-      # @param name [String] Type name to format.
-      # @param value [Object] Associated type detail.
-      # @return [String, nil] Formatted type entry, or nil when blank.
-      def format_hash_tag_type(name, value)
-        key = name.rstrip
-        return nil if key.empty?
-        return key if value.nil? || value == true || (value.respond_to?(:empty?) && value.empty?)
-
-        "#{key}: #{value}"
+        Array(types).map(&:to_s).map(&:strip).reject(&:empty?)
       end
     end
   end

data/lib/yard-markdown.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require "yard"
-require_relative "yard/markdown/anchor_component_helper"
 require_relative "yard/markdown/aref_helper"
 require_relative "yard/markdown/collection_rendering_helper"
 require_relative "yard/markdown/documentation_helper"