yard-markdown 0.5.0 → 0.7.0

data/example/rdoc/Bird.md

@@ -1,16 +1,11 @@
-# Class: Bird
-**Inherits:** Object
-    
-
-The base class for all birds.
-
+# Class Bird <a id="class-Bird"></a>
 
+**Inherits:** `Object`
 
-#Instance Methods
-## _fly_impl(_direction, _velocity) [](#method-i-_fly_impl)
-:nodoc:
+The base class for all birds.
 
-## fly(direction, velocity) [](#method-i-fly)
+## Public Instance Methods
+### `fly(direction, velocity)` <a id="method-i-fly"></a> <a id="fly-instance_method"></a>
 Fly somewhere.
 
 Flying is the most critical feature of birds.
@@ -25,8 +20,6 @@ Flying is the most critical feature of birds.
 
     fly(:south, 70)
 
-## speak() [](#method-i-speak)
+### `speak()` <a id="method-i-speak"></a> <a id="speak-instance_method"></a>
 Produce some noise. -- FIXME: maybe extract this to a base class `Animal`? ++
-
-**@yield** ["tweet"] 
-
+- **@yield** ["tweet"]

data/example/rdoc/Duck.md

@@ -1,10 +1,8 @@
-# Class: Duck
-**Inherits:** Object
-  
-**Extended by:** Animal
-    
-**Includes:** Waterfowl
-  
+# Class Duck <a id="class-Duck"></a>
+
+**Inherits:** `Object`
+**Extended by:** `Animal`
+**Includes:** `Waterfowl`
 
 A duck is a Waterfowl Bird.
 
@@ -19,42 +17,43 @@ Features:
 
       * swim
 
+## Constants
+### `@@rubber_ducks` <a id="classvariable--40-40rubber_ducks"></a> <a id="@@rubber_ducks-classvariable"></a>
+Global list of all rubber ducks.
+
+Use when in trouble.
 
-# Class Methods
-## rubber_ducks() [](#method-c-rubber_ducks)
-**@return** [Array<Duck>] list of all rubber ducks
+### `MAX_VELOCITY` <a id="constant-MAX_VELOCITY"></a> <a id="MAX_VELOCITY-constant"></a>
+Maximum velocity for a flying duck.
 
-# Attributes
-## domestic[RW] [](#attribute-i-domestic)
+## Attributes
+### `domestic` [RW] <a id="attribute-i-domestic"></a> <a id="domestic-instance_method"></a>
 True for domestic ducks.
 
-## rubber[RW] [](#attribute-i-rubber)
+### `rubber` [R] <a id="attribute-i-rubber"></a> <a id="rubber-instance_method"></a>
 True for rubber ducks.
 
+## Public Class Methods
+### `rubber_ducks()` <a id="method-c-rubber_ducks"></a> <a id="rubber_ducks-class_method"></a>
+- **@return** [Array<Duck>] list of all rubber ducks
 
-#Instance Methods
-## initialize(domestic, rubber) [](#method-i-initialize)
+## Public Instance Methods
+### `initialize(domestic, rubber)` <a id="method-i-initialize"></a> <a id="initialize-instance_method"></a>
 Creates a new duck.
+- **@param** `domestic` [Boolean]
+- **@param** `rubber` [Boolean]
+- **@return** [Duck] a new instance of Duck
 
-**@param** [Boolean] 
-
-**@param** [Boolean] 
-
-**@return** [Duck] a new instance of Duck
-
-## speak() [](#method-i-speak)
+### `speak()` <a id="method-i-speak"></a> <a id="speak-instance_method"></a>
 Duck overrides generic implementation.
+- **@yield** [speech]
 
-**@yield** [speech] 
-
-## swim() [](#method-i-swim)
+### `swim()` <a id="method-i-swim"></a> <a id="swim-instance_method"></a>
 Swimming helper.
 
-## useful?() [](#method-i-useful?)
+### `useful?()` <a id="method-i-useful-3F"></a> <a id="useful?-instance_method"></a>
 Checks if this duck is a useful one.
 
 :call-seq:
     Bird.useful? -> bool
-
-**@return** [Boolean] 
-
+- **@return** [Boolean]

data/example/rdoc/Waterfowl.md

@@ -1,11 +1,7 @@
-# Module: Waterfowl
-    
+# Module Waterfowl <a id="module-Waterfowl"></a>
 
 A mixin for waterfowl creatures.
 
-
-
-#Instance Methods
-## swim() [](#method-i-swim)
+## Public Instance Methods
+### `swim()` <a id="method-i-swim"></a> <a id="swim-instance_method"></a>
 Swimming helper.
-

data/example/rdoc/index.csv

@@ -1,21 +1,16 @@
 name,type,path
 Waterfowl,Module,Waterfowl.md
-Waterfowl.DEFAULT_DUCK_VELOCITY,Constant,Waterfowl.md#constant-DEFAULT_DUCK_VELOCITY
-Waterfowl.DEFAULT_SPEED,Constant,Waterfowl.md#constant-DEFAULT_SPEED
 Waterfowl.swim,Method,Waterfowl.md#method-i-swim
 Bird,Class,Bird.md
-Bird.DEFAULT_DUCK_VELOCITY,Constant,Bird.md#constant-DEFAULT_DUCK_VELOCITY
-Bird.DEFAULT_SPEED,Constant,Bird.md#constant-DEFAULT_SPEED
-Bird._fly_impl,Method,Bird.md#method-i-_fly_impl
 Bird.fly,Method,Bird.md#method-i-fly
 Bird.speak,Method,Bird.md#method-i-speak
 Duck,Class,Duck.md
-Duck.DEFAULT_DUCK_VELOCITY,Constant,Duck.md#constant-DEFAULT_DUCK_VELOCITY
-Duck.DEFAULT_SPEED,Constant,Duck.md#constant-DEFAULT_SPEED
+Duck.MAX_VELOCITY,Constant,Duck.md#constant-MAX_VELOCITY
+Duck.@@rubber_ducks,Constant,Duck.md#classvariable--40-40rubber_ducks
 Duck.initialize,Method,Duck.md#method-i-initialize
 Duck.speak,Method,Duck.md#method-i-speak
 Duck.swim,Method,Duck.md#method-i-swim
-Duck.useful?,Method,Duck.md#method-i-useful?
+Duck.useful?,Method,Duck.md#method-i-useful-3F
 Duck.rubber_ducks,Method,Duck.md#method-c-rubber_ducks
-domestic,Attribute,Duck.md#attribute-i-domestic
-rubber,Attribute,Duck.md#attribute-i-rubber
+Duck.domestic,Attribute,Duck.md#attribute-i-domestic
+Duck.rubber,Attribute,Duck.md#attribute-i-rubber

data/example/yard/Aquatic.md

@@ -1,13 +1,8 @@
-# Module: Aquatic
-    
+# Module Aquatic <a id="module-Aquatic"></a>
 
 A mixin for aquatic creatures.
 
-
-
-#Instance Methods
-## swim() [](#method-i-swim)
+## Public Instance Methods
+### `swim()` <a id="method-i-swim"></a> <a id="swim-instance_method"></a>
 Swim in the water.
-
-**@return** [void] 
-
+- **@return** [void]

data/example/yard/Fish.md

@@ -1,34 +1,25 @@
-# Class: Fish
-**Inherits:** Object
-    
-
-The base class for all fish.
+# Class Fish <a id="class-Fish"></a>
 
+**Inherits:** `Object`
 
+The base class for all fish.
 
-#Instance Methods
-## make_sound() [](#method-i-make_sound)
+## Public Instance Methods
+### `make_sound()` <a id="method-i-make_sound"></a> <a id="make_sound-instance_method"></a>
 Make a sound.
+- **@return** [void]
+- **@yield** [sound] The sound produced by the fish
+- **@yieldparam** `sound` [String] The actual sound
 
-**@return** [void] 
-
-**@yield** [sound] The sound produced by the fish
-
-**@yieldparam** [String] The actual sound
-
-## swim(direction, speed) [](#method-i-swim)
+### `swim(direction, speed)` <a id="method-i-swim"></a> <a id="swim-instance_method"></a>
 Swim in a specific direction.
 
 Swimming is the most critical feature of fish.
-
-**@param** [Symbol, String] The direction to swim
-
-**@param** [Integer] The speed at which to swim
-
-**@return** [Boolean] Whether the swim was successful
-
+- **@param** `direction` [Symbol, String] The direction to swim
+- **@param** `speed` [Integer] The speed at which to swim
+- **@return** [Boolean] Whether the swim was successful
 
 **@example**
 ```ruby
 swim(:north, 30)
-```
+```

data/example/yard/Salmon.md

@@ -1,8 +1,7 @@
-# Class: Salmon
-**Inherits:** Fish
-    
-**Includes:** Aquatic
-  
+# Class Salmon <a id="class-Salmon"></a>
+
+**Inherits:** `Fish`
+**Includes:** `Aquatic`
 
 A salmon is an Aquatic Fish.
 
@@ -14,47 +13,46 @@ A salmon is an Aquatic Fish.
 *   **Aquatic**
     *   swim (overridden)
 
+## Constants
+### Salmon specific attributes
+#### `MAX_SPEED` <a id="constant-MAX_SPEED"></a> <a id="MAX_SPEED-constant"></a>
+- **@return** [Integer] Maximum speed for a swimming salmon
+### General
+#### `@@wild_salmon` <a id="classvariable--40-40wild_salmon"></a> <a id="@@wild_salmon-classvariable"></a>
+Global list of all wild salmon.
 
-# Class Methods
-## wild_salmon() [](#method-c-wild_salmon)
-**@return** [Array<Salmon>] List of all wild salmon
-
-# Attributes
-## farmed[RW] [](#attribute-i-farmed)
-
-**@return** [Boolean] True for farmed salmon
-
-## wild[RW] [](#attribute-i-wild)
-
-**@return** [Boolean] True for wild salmon
-
-
-#Instance Methods
-## initialize(farmed, wild) [](#method-i-initialize)
-Creates a new salmon.
+Use for conservation efforts.
 
-**@param** [Boolean] Whether the salmon is farmed
+## Attributes
+### Salmon specific attributes
+#### `farmed` [RW] <a id="attribute-i-farmed"></a> <a id="farmed-instance_method"></a>
+- **@return** [Boolean] True for farmed salmon
 
-**@param** [Boolean] Whether the salmon is wild
+#### `wild` [R] <a id="attribute-i-wild"></a> <a id="wild-instance_method"></a>
+- **@return** [Boolean] True for wild salmon
 
-**@return** [Salmon] a new instance of Salmon
+## Public Class Methods
+### `wild_salmon()` <a id="method-c-wild_salmon"></a> <a id="wild_salmon-class_method"></a>
+- **@return** [Array<Salmon>] List of all wild salmon
 
-## make_sound() [](#method-i-make_sound)
+## Public Instance Methods
+### Fish overrides
+#### `make_sound()` <a id="method-i-make_sound"></a> <a id="make_sound-instance_method"></a>
 Salmon overrides generic implementation.
+- **@return** [void]
+- **@yield** [sound] The sound produced by the salmon
+- **@yieldparam** `sound` [String] The actual sound
+### General
+#### `initialize(farmed, wild)` <a id="method-i-initialize"></a> <a id="initialize-instance_method"></a>
+Creates a new salmon.
+- **@param** `farmed` [Boolean] Whether the salmon is farmed
+- **@param** `wild` [Boolean] Whether the salmon is wild
+- **@return** [Salmon] a new instance of Salmon
 
-**@return** [void] 
-
-**@yield** [sound] The sound produced by the salmon
-
-**@yieldparam** [String] The actual sound
-
-## sustainable?() [](#method-i-sustainable?)
+#### `sustainable?()` <a id="method-i-sustainable-3F"></a> <a id="sustainable?-instance_method"></a>
 Checks if this salmon is sustainable.
+- **@return** [Boolean] Whether the salmon is sustainable
 
-**@return** [Boolean] Whether the salmon is sustainable
-
-## swim() [](#method-i-swim)
+#### `swim()` <a id="method-i-swim"></a> <a id="swim-instance_method"></a>
 Swim in the water.
-
-**@return** [void] 
-
+- **@return** [void]

data/example/yard/index.csv

@@ -1,20 +1,16 @@
 name,type,path
 Aquatic,Module,Aquatic.md
-Aquatic.DEFAULT_SALMON_SPEED,Constant,Aquatic.md#constant-DEFAULT_SALMON_SPEED
-Aquatic.MAX_DEPTH,Constant,Aquatic.md#constant-MAX_DEPTH
 Aquatic.swim,Method,Aquatic.md#method-i-swim
 Fish,Class,Fish.md
-Fish.DEFAULT_SALMON_SPEED,Constant,Fish.md#constant-DEFAULT_SALMON_SPEED
-Fish.MAX_DEPTH,Constant,Fish.md#constant-MAX_DEPTH
 Fish.make_sound,Method,Fish.md#method-i-make_sound
 Fish.swim,Method,Fish.md#method-i-swim
 Salmon,Class,Salmon.md
-Salmon.DEFAULT_SALMON_SPEED,Constant,Salmon.md#constant-DEFAULT_SALMON_SPEED
-Salmon.MAX_DEPTH,Constant,Salmon.md#constant-MAX_DEPTH
+Salmon.MAX_SPEED,Constant,Salmon.md#constant-MAX_SPEED
+Salmon.@@wild_salmon,Constant,Salmon.md#classvariable--40-40wild_salmon
 Salmon.initialize,Method,Salmon.md#method-i-initialize
 Salmon.make_sound,Method,Salmon.md#method-i-make_sound
-Salmon.sustainable?,Method,Salmon.md#method-i-sustainable?
+Salmon.sustainable?,Method,Salmon.md#method-i-sustainable-3F
 Salmon.swim,Method,Salmon.md#method-i-swim
 Salmon.wild_salmon,Method,Salmon.md#method-c-wild_salmon
-farmed,Attribute,Salmon.md#attribute-i-farmed
-wild,Attribute,Salmon.md#attribute-i-wild
+Salmon.farmed,Attribute,Salmon.md#attribute-i-farmed
+Salmon.wild,Attribute,Salmon.md#attribute-i-wild

data/lib/yard/markdown/anchor_component_helper.rb

@@ -0,0 +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
+    # 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 [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
+    end
+  end
+end

data/lib/yard/markdown/aref_helper.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module YARD
+  module Markdown
+    # Computes anchor ids that match the generated Markdown headings.
+    module ArefHelper
+      include AnchorComponentHelper
+
+      # Returns the primary anchor id for a documented object.
+      #
+      # @param object [YARD::CodeObjects::Base] Object being rendered.
+      # @return [String] Anchor id for the object's heading.
+      def aref(object)
+        type = object.type
+
+        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'
+
+        if !object.attr_info.nil?
+          "attribute-#{scope}-#{object.name}"
+        else
+          "method-#{scope}-#{anchor_component(object.name)}"
+        end
+      end
+    end
+  end
+end

data/lib/yard/markdown/collection_rendering_helper.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module YARD
+  module Markdown
+    # Renders grouped Markdown sections for constants, attributes, and methods.
+    module CollectionRenderingHelper
+      # Renders the constants section for an object page.
+      #
+      # @param constants [Array<YARD::CodeObjects::Base>] Constant objects collected for the current page.
+      # @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")
+      end
+
+      # Renders the attributes section for an object page.
+      #
+      # @param attrs [Array<YARD::CodeObjects::MethodObject>] Attributes to render.
+      # @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")
+      end
+
+      # Renders a method section for an object page.
+      #
+      # @param section_title [String] Section title to render.
+      # @param methods [Array<YARD::CodeObjects::MethodObject>] Method objects collected for the current section.
+      # @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)
+        lines = ["## #{section_title}"]
+        grouped_methods = grouped_items(methods, group_order)
+        uses_groups = grouped_methods.any? { |name, _items| !name.nil? }
+
+        grouped_methods.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} `#{formatted_method_heading(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")
+      end
+    end
+  end
+end

data/lib/yard/markdown/documentation_helper.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require 'rdoc'
+
+module YARD
+  module Markdown
+    # Converts YARD docstrings into Markdown-friendly text.
+    module DocumentationHelper
+      # Returns the rendered documentation text for an object.
+      #
+      # @param object [YARD::CodeObjects::Base] Object whose docstring is being rendered.
+      # @return [String] Converted documentation text or a fallback message.
+      def documented_text(object)
+        text = rdoc_to_md(object.docstring)
+        return text unless text.empty?
+        return '' unless object.tags.empty?
+
+        'Not documented.'
+      end
+
+      # Converts an RDoc-formatted docstring to Markdown.
+      #
+      # @param docstring [Object] Raw docstring content.
+      # @return [String] Markdown-rendered docstring content.
+      def rdoc_to_md(docstring)
+        RDoc::Markup::ToMarkdown.new.convert(docstring).rstrip
+      end
+    end
+  end
+end

data/lib/yard/markdown/heading_helper.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module YARD
+  module Markdown
+    # Builds headings and legacy anchors for rendered object sections.
+    module HeadingHelper
+      include ArefHelper
+
+      # Returns the legacy YARD anchor for an object when one exists.
+      #
+      # @param object [YARD::CodeObjects::Base] Object being rendered.
+      # @return [String, nil] Legacy anchor id, if supported.
+      def legacy_aref(object)
+        type = object.type
+
+        return "#{object.name}-constant" if type == :constant
+        return "#{object.name}-classvariable" if type == :classvariable
+        return nil unless object.respond_to?(:scope)
+
+        return "#{object.name}-class_method" if object.scope == :class
+
+        "#{object.name}-instance_method"
+      end
+
+      # Returns all anchor tags that should be attached to a heading.
+      #
+      # @param object [YARD::CodeObjects::Base] Object being rendered.
+      # @return [Array<String>] HTML anchor tags for the object.
+      def anchor_tags_for(object)
+        anchors = [aref(object), legacy_aref(object)].compact
+        anchors.map { |id| anchor_tag(id) }
+      end
+
+      # Appends the generated anchor tags to a Markdown heading.
+      #
+      # @param heading [String] Heading text to decorate.
+      # @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(' ')}"
+      end
+
+      # Builds an HTML anchor tag for a generated id.
+      #
+      # @param id [String] Anchor id value.
+      # @return [String] HTML anchor tag.
+      def anchor_tag(id)
+        %(<a id="#{id}"></a>)
+      end
+    end
+  end
+end