yard-markdown 0.3.5 → 0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c227b04d5aa3f58fc394afa96321c60f39d9975145476f5f7ac53453f5d58b29
-  data.tar.gz: a55a8c70d0afcdfe7a540e74f24922bc31ac161740576afee9d5e5d18bac318a
+  metadata.gz: 3df94167400db27cf5f4262cc1ac0b800b36108356092de9cb7329805ea113e4
+  data.tar.gz: e962872fd8536827202d6488497ef698bf7484a95880d0539edb6f6428546d32
 SHA512:
-  metadata.gz: fe9dd35f306722d000d1fbc1271f526c9f80698ee5ee223d17f94a36a1ca315734d183745674d5cb2e42a470454d2cc6879ac8bbbb0b8f1a3e6902571de0a4e0
-  data.tar.gz: 19f382bc86ef7722f92f520129bb0d7ddda7b8ecd3b6f8214ee663c5397eb102b866c2ad73f9a4d7250f89748f3fbf540cb20f164d6fb7b2c44fc2e104a78a81
+  metadata.gz: '08cddd7156921c807a951fe1774857178be755bf915cea81fa3c288bdc8e3b8f2a9c66fd5bf7a2b5ea1db33729e8524b95c400ec8f049dc49887fdac279b2f35'
+  data.tar.gz: 86f49d74fd82a79e31acaf8524d473eea7d96fac7012975fc957bff4d9f88101f6ca65ca51e9d0da348a789c6c09c1803806f34b4123c17308f04762875884b5

data/README.md

@@ -31,4 +31,8 @@ This is a successor to [rdoc-mardown gem](https://github.com/skatkov/rdoc-markdo
 ## Testing
 Unit tests can't really test this gem properly. So it's semi-manual process of making changes and reviewing output.
 
-  `yardoc example.rb` -> outputs everything into example/ folder.
+Testing Rdoc conversion to markdown:
+  `yardoc example_rdoc.rb` -> outputs everything into example/ folder.
+
+Testing Yard conversion to markdown:
+  `yardoc example_yard.rb` -> outputs everything into example/ folder.

data/example/Aquatic.md

@@ -0,0 +1,20 @@
+# Module: Aquatic
+    
+**Defined in:** example_yard.rb
+
+A mixin for aquatic creatures.
+
+# Public Instance Methods
+## swim() [](#method-i-swim)
+Swim in the water.
+
+**return** [void] 
+
+
+# Constants
+## DEFAULT_SALMON_SPEED [](#constant-DEFAULT_SALMON_SPEED)
+
+
+## MAX_DEPTH [](#constant-MAX_DEPTH)
+
+

data/example/Fish.md

@@ -0,0 +1,35 @@
+# Class: Fish
+**Inherits:** Object
+    
+**Defined in:** example_yard.rb
+
+The base class for all fish.
+
+# Public Instance Methods
+## make_sound() [](#method-i-make_sound)
+Make a sound.
+
+**return** [void] 
+**yield** [sound] The sound produced by the fish
+**yieldparam** [String] The actual sound
+## swim(direction, speed) [](#method-i-swim)
+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
+
+**example**
+```ruby
+swim(:north, 30)
+```
+
+# Constants
+## DEFAULT_SALMON_SPEED [](#constant-DEFAULT_SALMON_SPEED)
+
+
+## MAX_DEPTH [](#constant-MAX_DEPTH)
+
+

data/example/Salmon.md

@@ -0,0 +1,58 @@
+# Class: Salmon
+**Inherits:** Fish
+    
+**Includes:** Aquatic
+  
+**Defined in:** example_yard.rb
+
+A salmon is an Aquatic Fish.
+
+## Features
+
+*   **Fish**
+    *   make_sound
+    *   swim
+*   **Aquatic**
+    *   swim (overridden)
+
+# Public Instance Methods
+## initialize(farmed, wild) [](#method-i-initialize)
+Creates a new salmon.
+
+**param** [Boolean] Whether the salmon is farmed
+**param** [Boolean] Whether the salmon is wild
+**return** [Salmon] a new instance of Salmon
+## make_sound() [](#method-i-make_sound)
+Salmon overrides generic implementation.
+
+**return** [void] 
+**yield** [sound] The sound produced by the salmon
+**yieldparam** [String] The actual sound
+## sustainable?() [](#method-i-sustainable?)
+Checks if this salmon is sustainable.
+
+**return** [Boolean] Whether the salmon is sustainable
+## swim() [](#method-i-swim)
+Swim in the water.
+
+**return** [void] 
+
+# Public 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
+
+# Constants
+## DEFAULT_SALMON_SPEED [](#constant-DEFAULT_SALMON_SPEED)
+
+
+## MAX_DEPTH [](#constant-MAX_DEPTH)
+
+

data/example/index.csv

@@ -1,21 +1,20 @@
 name,type,path
-Waterfowl,Module,Waterfowl.md
-DEFAULT_DUCK_VELOCITY,Constant,Waterfowl.md#constant-DEFAULT_DUCK_VELOCITY
-DEFAULT_SPEED,Constant,Waterfowl.md#constant-DEFAULT_SPEED
-swim,Method,Waterfowl.md#method-i-swim
-Bird,Class,Bird.md
-DEFAULT_DUCK_VELOCITY,Constant,Bird.md#constant-DEFAULT_DUCK_VELOCITY
-DEFAULT_SPEED,Constant,Bird.md#constant-DEFAULT_SPEED
-_fly_impl,Method,Bird.md#method-i-_fly_impl
-fly,Method,Bird.md#method-i-fly
-speak,Method,Bird.md#method-i-speak
-Duck,Class,Duck.md
-DEFAULT_DUCK_VELOCITY,Constant,Duck.md#constant-DEFAULT_DUCK_VELOCITY
-DEFAULT_SPEED,Constant,Duck.md#constant-DEFAULT_SPEED
-initialize,Method,Duck.md#method-i-initialize
-speak,Method,Duck.md#method-i-speak
-swim,Method,Duck.md#method-i-swim
-useful?,Method,Duck.md#method-i-useful?
-rubber_ducks,Method,Duck.md#method-c-rubber_ducks
-domestic,Attribute,Duck.md#attribute-i-domestic
-rubber,Attribute,Duck.md#attribute-i-rubber
+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.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.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

data/example_yard.rb

@@ -0,0 +1,154 @@
+# @title YARD Markdown Example
+# @description This example demonstrates various YARD features using markdown formatting.
+#
+# ## Links
+#
+# 1. [YARD Documentation](https://yardoc.org/)
+# 2. [Markdown Syntax](https://daringfireball.net/projects/markdown/syntax)
+
+# A mixin for aquatic creatures.
+module Aquatic
+  # Swim in the water.
+  #
+  # @return [void]
+  def swim
+    puts "swimming in the water"
+  end
+end
+
+# The base class for all fish.
+class Fish
+  # Make a sound.
+  #
+  # @yield [sound] The sound produced by the fish
+  # @yieldparam sound [String] The actual sound
+  # @return [void]
+  def make_sound
+    puts "generic bubbling"
+    yield "blub"
+    yield "blub"
+  end
+
+  # Swim in a specific direction.
+  #
+  # Swimming is the most critical feature of fish.
+  #
+  # @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
+  #   swim(:north, 30)
+  def swim(direction, speed)
+    _swim_impl(direction, speed)
+  end
+
+  private
+
+  # @!visibility private
+  def _swim_impl(direction, speed)
+    puts "swimming away: direction=#{direction}, speed=#{speed}"
+  end
+end
+
+# A salmon is an Aquatic Fish.
+#
+# ## Features
+#
+# - **Fish**
+#   - make_sound
+#   - swim
+# - **Aquatic**
+#   - swim (overridden)
+class Salmon < Fish
+  include Aquatic
+
+  # @!group Fish overrides
+
+  # Salmon overrides generic implementation.
+  #
+  # @yield [sound] The sound produced by the salmon
+  # @yieldparam sound [String] The actual sound
+  # @return [void]
+  def make_sound
+    sound = splash
+    yield sound
+  end
+
+  # Implements splashing
+  #
+  # @return [String] The splash sound
+  def splash
+    "splash"
+  end
+
+  private :splash
+
+  # @!endgroup
+
+  # @!group Salmon specific attributes
+
+  # @return [Boolean] True for farmed salmon
+  attr_accessor :farmed
+
+  # @return [Boolean] True for wild salmon
+  attr_reader :wild
+
+  # @return [Integer] Maximum speed for a swimming salmon
+  MAX_SPEED = 40
+
+  # @!endgroup
+
+  # Global list of all wild salmon.
+  #
+  # Use for conservation efforts.
+  @@wild_salmon = []
+
+  # @return [Array<Salmon>] List of all wild salmon
+  def self.wild_salmon
+    @@wild_salmon
+  end
+
+  # Creates a new salmon.
+  #
+  # @param farmed [Boolean] Whether the salmon is farmed
+  # @param wild [Boolean] Whether the salmon is wild
+  def initialize(farmed, wild)
+    @farmed = farmed
+    @wild = wild
+    @@wild_salmon << self if wild
+  end
+
+  # Checks if this salmon is sustainable.
+  #
+  # @return [Boolean] Whether the salmon is sustainable
+  def sustainable?
+    @wild || (@farmed && environmentally_friendly?)
+  end
+
+  private
+
+  # @return [Boolean] Whether farming practices are environmentally friendly
+  def environmentally_friendly?
+    # Implementation details...
+    true
+  end
+end
+
+# @!constant [Integer] DEFAULT_SALMON_SPEED
+#   Default speed for a swimming salmon
+DEFAULT_SALMON_SPEED = 20
+
+# @!constant [Integer] MAX_DEPTH
+#   Maximum depth for salmon habitat
+MAX_DEPTH = 500
+
+# Default wild salmon.
+#
+# @note Global variables should be used sparingly, but this is for demonstration.
+$default_wild_salmon = Salmon.new(false, true)
+
+# Farmed sustainable salmon.
+#
+# @note This is just a local variable for demonstration purposes.
+farmed_sustainable_salmon = Salmon.new(true, false)

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

@@ -50,7 +50,7 @@ def serialize_index(objects)
       if constant_listing.size.positive?
         constant_listing.each do |cnst|
           csv << [
-            cnst.name(false),
+            "#{object.path}.#{cnst.name(false)}",
             "Constant",
             (options.serializer.serialized_path(object) + "#" + aref(cnst)),
           ]
@@ -60,7 +60,7 @@ def serialize_index(objects)
       if (insmeths = public_instance_methods(object)).size > 0
         insmeths.each do |item|
           csv << [
-            item.name(false),
+            "#{object.path}.#{item.name(false)}",
             "Method",
             options.serializer.serialized_path(object) + "#" + aref(item),
           ]
@@ -70,7 +70,7 @@ def serialize_index(objects)
       if (pubmeths = public_class_methods(object)).size > 0
         pubmeths.each do |item|
           csv << [
-            item.name(false),
+            "#{object.path}.#{item.name(false)}",
             "Method",
             options.serializer.serialized_path(object) + "#" + aref(item),
           ]
@@ -90,6 +90,10 @@ def serialize_index(objects)
   end
 end
 
+# @param object [YARD::CodeObjects::Base]
+# @return [String] markdown formatted string
+#
+# @todo Extract template out of setup.rb class.
 def serialize(object)
   template =
     ERB.new(
@@ -106,12 +110,14 @@ def serialize(object)
 
 <%= rdoc_to_md object.docstring %>
 
+<%= render_tags object %>
 <% if (insmeths = public_instance_methods(object)).size > 0 %>
 # Public Instance Methods
 <% insmeths.each do |item| %>
 ## <%= item.name(false) %>(<%= item.parameters.map {|p| p.join("") }.join(", ")%>) [](#<%=aref(item)%>)
 <%= rdoc_to_md item.docstring %>
 
+<%= render_tags item %>
 <% end %><% end %>
 
 <% if (pubmeths = public_class_methods(object)).size > 0 %>
@@ -119,6 +125,7 @@ def serialize(object)
 <% pubmeths.each do |item| %>
 ## <%= item.name(false) %>(<%= item.parameters.map {|p| p.join(" ") }.join(", ") %>) [](#<%=aref(item)%>)
 <%= rdoc_to_md item.docstring %>
+<%= render_tags item %>
 
 <% end %>
 <% end %>
@@ -128,6 +135,7 @@ def serialize(object)
 ## <%= item.name %><%= item.reader? ? "[RW]" : "[R]" %> [](#<%=aref(item)%>)
 <%= rdoc_to_md item.docstring %>
 
+<%= render_tags item %>
 <% end %>
 <% end %>
 
@@ -138,6 +146,8 @@ def serialize(object)
 ## <%= cnst.name %> [](#<%=aref(cnst)%>)
 <%= rdoc_to_md cnst.docstring %>
 
+<%= render_tags cnst %>
+
 <% end %><% end %><% end %>',
       trim_mode: "<>",
     )
@@ -147,10 +157,50 @@ end
 
 require "rdoc"
 
+##
+# Converts rdoc to markdown.
+#
+# I didn't found a way to detect yard/rdoc docstrings, so we're running docstrings through rdoc to markdown converter in all cases. If it's yard docstring, it doesn't seem to have any negative effect on end results. But absense of bugs, doesn't mean that there are no issues.
+#
+# @param docstring [String, YARD::Docstring]
+# @return [String] markdown formatted string
 def rdoc_to_md(docstring)
   RDoc::Markup::ToMarkdown.new.convert(docstring)
 end
 
+##
+# Formats yard tags belonging to a object.
+#
+# This is mostly a feature of yard and rdoc doesn't have any of that. Rdoc supports ":nodoc:" and other tags. Yard claims to have full support for rdoc, doesn't really handle tags like ":nodoc:" or anything else from rdoc.
+#
+# There is an attempt to handle @example tag differently, we surround it with a code block.
+#
+# @see https://rubydoc.info/gems/yard/file/docs/TagsArch.md
+#
+# @param object [YARD::CodeObjects::Base]
+# @return [String] markdown formatted string of Tags
+
+def render_tags(object)
+  result = String.new("")
+  object.tags.each do |tag|
+    result << if !(tag.tag_name == "example")
+      "**@#{tag.tag_name}** [#{tag.types&.join(', ')}] #{tag.text}\n"
+    else
+      ""
+    end
+  end
+
+  object.tags.each do |tag|
+    result << if (tag.tag_name == "example")
+      "\n**@#{tag.tag_name}**\n```ruby\n#{tag.text}\n```"
+    else
+      ""
+    end
+  end
+
+  result
+end
+
 def aref(object)
   if object.type == :constant
     "constant-#{object.name(false)}"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: yard-markdown
 version: !ruby/object:Gem::Version
-  version: 0.3.5
+  version: '0.4'
 platform: ruby
 authors:
 - Stanislav (Stas) Katkov
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-08-25 00:00:00.000000000 Z
+date: 2024-12-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: yard
@@ -24,6 +24,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: csv
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: yard plugin to generate markdown documentation for gems
 email:
 - yard-markdown@skatkov.com
@@ -37,13 +51,12 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
-- example.rb
-- example/Bird.md
-- example/Duck.md
-- example/Waterfowl.md
-- example/YARD.md
-- example/YARD/Markdown.md
+- example/Aquatic.md
+- example/Fish.md
+- example/Salmon.md
 - example/index.csv
+- example_rdoc.rb
+- example_yard.rb
 - lib/yard-markdown.rb
 - sig/yard/markdown.rbs
 - templates/default/fulldoc/markdown/setup.rb
@@ -68,7 +81,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.17
+rubygems_version: 3.5.9
 signing_key:
 specification_version: 4
 summary: yard plugin to generate markdown documentation

data/example/Bird.md

@@ -1,38 +0,0 @@
-# Class: Bird
-**Inherits:** Object
-    
-**Defined in:** example.rb
-
-The base class for all birds.
-
-# Public Instance Methods
-## _fly_impl(_direction, _velocity) [](#method-i-_fly_impl)
-:nodoc:
-
-## fly(direction, velocity) [](#method-i-fly)
-Fly somewhere.
-
-Flying is the most critical feature of birds.
-
-:args: direction, velocity
-
-:call-seq:
-    Bird.fly(symbol, number) -> bool
-    Bird.fly(string, number) -> bool
-
-# Example
-
-    fly(:south, 70)
-
-## speak() [](#method-i-speak)
-Produce some noise. -- FIXME: maybe extract this to a base class `Animal`? ++
-
-
-
-# Constants
-## DEFAULT_DUCK_VELOCITY [](#constant-DEFAULT_DUCK_VELOCITY)
-Default velocity for a flying duck.
-
-## DEFAULT_SPEED [](#constant-DEFAULT_SPEED)
-Maximum speed for a swimming duck.
-

data/example/Duck.md

@@ -1,57 +0,0 @@
-# Class: Duck
-**Inherits:** Object
-  
-**Extended by:** Animal
-    
-**Includes:** Waterfowl
-  
-**Defined in:** example.rb
-
-A duck is a Waterfowl Bird.
-
-Features:
-
-    bird::
-
-      * speak
-      * fly
-
-    waterfowl::
-
-      * swim
-
-# Public Instance Methods
-## initialize(domestic, rubber) [](#method-i-initialize)
-Creates a new duck.
-
-## speak() [](#method-i-speak)
-Duck overrides generic implementation.
-
-## swim() [](#method-i-swim)
-Swimming helper.
-
-## useful?() [](#method-i-useful?)
-Checks if this duck is a useful one.
-
-:call-seq:
-    Bird.useful? -> bool
-
-
-# Public Class Methods
-## rubber_ducks() [](#method-c-rubber_ducks)
-
-# Attributes
-## domestic[RW] [](#attribute-i-domestic)
-True for domestic ducks.
-
-## rubber[RW] [](#attribute-i-rubber)
-True for rubber ducks.
-
-
-# Constants
-## DEFAULT_DUCK_VELOCITY [](#constant-DEFAULT_DUCK_VELOCITY)
-Default velocity for a flying duck.
-
-## DEFAULT_SPEED [](#constant-DEFAULT_SPEED)
-Maximum speed for a swimming duck.
-

data/example/Waterfowl.md

@@ -1,19 +0,0 @@
-# Module: Waterfowl
-    
-**Defined in:** example.rb
-
-A mixin for waterfowl creatures.
-
-# Public Instance Methods
-## swim() [](#method-i-swim)
-Swimming helper.
-
-
-
-# Constants
-## DEFAULT_DUCK_VELOCITY [](#constant-DEFAULT_DUCK_VELOCITY)
-Default velocity for a flying duck.
-
-## DEFAULT_SPEED [](#constant-DEFAULT_SPEED)
-Maximum speed for a swimming duck.
-

data/example/YARD/Markdown.md

@@ -1,10 +0,0 @@
-# Module: YARD::Markdown
-| | |
-| -----------------:  | :-----    |
-| **Defined in:**    | lib/yard-markdown.rb    |
-
-
-
-
-
-

data/example/YARD.md

@@ -1,10 +0,0 @@
-# Module: YARD
-| | |
-| -----------------:  | :-----    |
-| **Defined in:**    | lib/yard-markdown.rb    |
-
-
-
-
-
-