yard-markdown 0.3.6 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f5523cfc6cf6adb6b59889cd2e0d6bfc77c1fb52383082e3c9301e0844a2d560
-  data.tar.gz: 0fe11f9cae202f92339a483944ec2ef5fa8f7691df97956ebe25a94ceaf1d754
+  metadata.gz: 56b8294ee2ef9bdd12b36f03b4260286e34d2002363a4f9cd280af85743c342c
+  data.tar.gz: f8df2867ca6d8c98aa79a20585d181b79ed12a507637b948708010ae2930ffe4
 SHA512:
-  metadata.gz: 72da1d6db9b4973eece057cf270a2a51bed95755b02a99aac9f17bbdc4ad77d6dd5446be046851c1c03d3905815205f7aed708c98b0ae989202f15fc44710aff
-  data.tar.gz: 643b0905f46830b7108ea6fa9021ff3306679ed534b6e294cd02e0d069ad1cce3bca04a190ea20c8344f7ee3bf2f97a479044d5519e9b027a9806d22c2dab16d
+  metadata.gz: 5d814cb9ac75d6330b72bbd53087fbc417392aa44296944da168f4195b7d92a9d60ff5e5e40d233ad628763c2c7d9cdb9c99213dde740dd54478791fce1bdacd
+  data.tar.gz: 1aba7f70acf91dca5f5b2a829160ff255a60a598360ccfce492d6cd2096a3d110095fb1eac6bf38138fab808ed98cc6b8b517598acd71a69cc658e235b47012e

data/README.md

@@ -6,7 +6,6 @@ Yard plugin to generate markdown documentation
 - Compatible with Github Flavored Markdown
 - Mimick yard html layout where it makes sense to maintain familiarity
 - Produce .csv index file alonside markdown documentation to act as file index
-- Include markdown files that are already present in source code.
 
 ## Usage
 Yard doesn't load plugin by default, so you need to load plugin through `~/.yard/config`:
@@ -26,9 +25,13 @@ gem install yard-markdown
 Run `yardoc --format=markdown` to generate markdown documentation.
 
 ## Backstory
-This is a successor to [rdoc-mardown gem](https://github.com/skatkov/rdoc-markdown/tree/main/example) with small differences in implementation. This gem was written to power API documentation browser CLI app for ruby developers called [POSH TUI](https://poshtui.com).
+This is a successor to [rdoc-mardown gem](https://github.com/skatkov/rdoc-markdown/tree/main/example). These docsets are used in [POSH TUI](https://poshtui.com).
 
 ## 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,18 @@
+# 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
+| Name | Default Value |
+| ---  | ---   |
+| [DEFAULT_SALMON_SPEED](#constant-DEFAULT_SALMON_SPEED) | 20 |
+| [MAX_DEPTH](#constant-MAX_DEPTH) | 500 |

data/example/Fish.md

@@ -0,0 +1,33 @@
+# 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
+| Name | Default Value |
+| ---  | ---   |
+| [DEFAULT_SALMON_SPEED](#constant-DEFAULT_SALMON_SPEED) | 20 |
+| [MAX_DEPTH](#constant-MAX_DEPTH) | 500 |

data/example/Salmon.md

@@ -0,0 +1,56 @@
+# 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
+| Name | Default Value |
+| ---  | ---   |
+| [DEFAULT_SALMON_SPEED](#constant-DEFAULT_SALMON_SPEED) | 20 |
+| [MAX_DEPTH](#constant-MAX_DEPTH) | 500 |

data/example/index.csv

@@ -1,21 +1,20 @@
 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.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.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,145 @@
+# 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
+
+# Default speed for a swimming salmon
+DEFAULT_SALMON_SPEED = 20
+
+#   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

@@ -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,26 +125,25 @@ def serialize(object)
 <% pubmeths.each do |item| %>
 ## <%= item.name(false) %>(<%= item.parameters.map {|p| p.join(" ") }.join(", ") %>) [](#<%=aref(item)%>)
 <%= rdoc_to_md item.docstring %>
-
-<% end %>
-<% end %>
+<%= render_tags item %>
+<% end %><% end %>
 <% if (attrs = attr_listing(object)).size > 0 %>
 # Attributes
 <% attrs.each do |item|%>
 ## <%= item.name %><%= item.reader? ? "[RW]" : "[R]" %> [](#<%=aref(item)%>)
 <%= rdoc_to_md item.docstring %>
 
-<% end %>
-<% end %>
-
+<%= render_tags item %>
+<% end %><% end %>
 <% if constant_listing.size > 0 %>
 <% groups(constant_listing, "Constants") do |list, name| %>
 # <%= name %>
+<% if list.size > 0 %>
+| Name | Default Value |
+| ---  | ---   |
 <% list.each do |cnst| %>
-## <%= cnst.name %> [](#<%=aref(cnst)%>)
-<%= rdoc_to_md cnst.docstring %>
-
-<% end %><% end %><% end %>',
+| [<%= cnst.name %>](#<%=aref(cnst)%>) | <%= cnst.value %> |
+<% end %><% end %><% end %><% end %>',
       trim_mode: "<>",
     )
 
@@ -147,10 +152,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.6
+  version: 0.4.1
 platform: ruby
 authors:
 - Stanislav (Stas) Katkov
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-09-09 00:00:00.000000000 Z
+date: 2024-12-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: yard
@@ -51,11 +51,12 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
-- example.rb
-- example/Bird.md
-- example/Duck.md
-- example/Waterfowl.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

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.
-