yard-markdown 0.4.1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 56b8294ee2ef9bdd12b36f03b4260286e34d2002363a4f9cd280af85743c342c
-  data.tar.gz: f8df2867ca6d8c98aa79a20585d181b79ed12a507637b948708010ae2930ffe4
+  metadata.gz: b3bf19f52aa053b77b3bdfa88b447e7db00c746135a47b77e81e2a08ceb4367a
+  data.tar.gz: 8a141a935807d808abec2fa5f2e6d690cfb0c9ec70e89fc0709e7a39f60fb697
 SHA512:
-  metadata.gz: 5d814cb9ac75d6330b72bbd53087fbc417392aa44296944da168f4195b7d92a9d60ff5e5e40d233ad628763c2c7d9cdb9c99213dde740dd54478791fce1bdacd
-  data.tar.gz: 1aba7f70acf91dca5f5b2a829160ff255a60a598360ccfce492d6cd2096a3d110095fb1eac6bf38138fab808ed98cc6b8b517598acd71a69cc658e235b47012e
+  metadata.gz: d53e7cd3f76693122642ec6196bf8e49f11b2b5457ebb0942be702e33efe25348141580188bb00dfc9846b5766ee412e14c9c059e119358ab79c1a0f828e30c1
+  data.tar.gz: 02d47f00d6408f1d645ac0d46936e2734c89f1c853632d88b4217d0bb2985993ddcd6d99dbe38de18ee40a858b1441a35b44c3ce7e6ea2161b4a6705e2dcb540

data/.yardopts

@@ -1,8 +1 @@
 --load ./lib/yard-markdown.rb
---format markdown
---markup markdown
---output-dir example
---private
---protected
--
-example.rb

data/README.md

@@ -1,11 +1,15 @@
 # Yard::Markdown
 
-Yard plugin to generate markdown documentation
+Yard plugin to output markdown documentation.
+
+## Motivation
+Markdown has become the de-facto documentation standard. I heavily rely on Obsidian to render my storage of markdown notes. But markdown is used not just for scribbles, supported is far and wide. We can render markdown file on any device, probably even on thermometer with a screen. But also everyone knows enough markdown to be dangerous (or productive).
+It's a pitty that rdoc and yard can't output a proper markdown file. I would like to change that.
 
 ## Goals:
 - Compatible with Github Flavored Markdown
+- Produce .csv index file
 - Mimick yard html layout where it makes sense to maintain familiarity
-- Produce .csv index file alonside markdown documentation to act as file index
 
 ## Usage
 Yard doesn't load plugin by default, so you need to load plugin through `~/.yard/config`:
@@ -24,14 +28,21 @@ 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). These docsets are used in [POSH TUI](https://poshtui.com).
+## 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-mardown gem](https://github.com/skatkov/rdoc-markdown/).
+
+## 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.
 
 ## Testing
 Unit tests can't really test this gem properly. So it's semi-manual process of making changes and reviewing output.
 
-### 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.
+Easiest way to test is to run `rake generate_example` and check output in `example` directory.

data/Rakefile

@@ -10,3 +10,22 @@ Rake::TestTask.new(:test) do |t|
 end
 
 task default: %i[test stree:write]
+
+
+namespace :examples do
+  desc "Generate basic example documentation using yard-markdown plugin"
+  task :generate do
+    Rake::Task["examples:yard"].invoke
+    Rake::Task["examples:rdoc"].invoke
+  end
+
+  desc "Generate example documentation for code annotated with yard"
+  task :yard do
+    sh "yardoc --output-dir example/yard example_yard.rb"
+  end
+
+  desc "Generate example documentation for code annotated with rdoc"
+  task :rdoc do
+    sh "yardoc --output-dir example/rdoc example_rdoc.rb"
+  end
+end

data/example/rdoc/Bird.md

@@ -0,0 +1,32 @@
+# Class: Bird
+**Inherits:** Object
+    
+
+The base class for all birds.
+
+
+
+#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`? ++
+
+**@yield** ["tweet"] 
+

data/example/rdoc/Duck.md

@@ -0,0 +1,60 @@
+# Class: Duck
+**Inherits:** Object
+  
+**Extended by:** Animal
+    
+**Includes:** Waterfowl
+  
+
+A duck is a Waterfowl Bird.
+
+Features:
+
+    bird::
+
+      * speak
+      * fly
+
+    waterfowl::
+
+      * swim
+
+
+# Class Methods
+## rubber_ducks() [](#method-c-rubber_ducks)
+**@return** [Array<Duck>] list of all rubber ducks
+
+# Attributes
+## domestic[RW] [](#attribute-i-domestic)
+True for domestic ducks.
+
+## rubber[RW] [](#attribute-i-rubber)
+True for rubber ducks.
+
+
+#Instance Methods
+## initialize(domestic, rubber) [](#method-i-initialize)
+Creates a new duck.
+
+**@param** [Boolean] 
+
+**@param** [Boolean] 
+
+**@return** [Duck] a new instance of Duck
+
+## speak() [](#method-i-speak)
+Duck overrides generic implementation.
+
+**@yield** [speech] 
+
+## swim() [](#method-i-swim)
+Swimming helper.
+
+## useful?() [](#method-i-useful?)
+Checks if this duck is a useful one.
+
+:call-seq:
+    Bird.useful? -> bool
+
+**@return** [Boolean] 
+

data/example/rdoc/Waterfowl.md

@@ -0,0 +1,11 @@
+# Module: Waterfowl
+    
+
+A mixin for waterfowl creatures.
+
+
+
+#Instance Methods
+## swim() [](#method-i-swim)
+Swimming helper.
+

data/example/rdoc/index.csv

@@ -0,0 +1,21 @@
+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

data/example/yard/Aquatic.md

@@ -0,0 +1,13 @@
+# Module: Aquatic
+    
+
+A mixin for aquatic creatures.
+
+
+
+#Instance Methods
+## swim() [](#method-i-swim)
+Swim in the water.
+
+**@return** [void] 
+

data/example/{Fish.md → yard/Fish.md}

@@ -1,33 +1,34 @@
 # Class: Fish
 **Inherits:** Object
     
-**Defined in:** example_yard.rb
 
 The base class for all fish.
 
-# Public Instance Methods
+
+
+#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 → yard/Salmon.md}

@@ -3,7 +3,6 @@
     
 **Includes:** Aquatic
   
-**Defined in:** example_yard.rb
 
 A salmon is an Aquatic Fish.
 
@@ -15,42 +14,47 @@ A salmon is an Aquatic Fish.
 *   **Aquatic**
     *   swim (overridden)
 
-# Public Instance Methods
+
+# 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.
 
 **@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/templates/default/fulldoc/markdown/setup.rb

@@ -104,24 +104,13 @@ def serialize(object)
   <% if (mix = run_verifier(object.mixins(scope))).size > 0 %>
 **<%= name %>:** <%= mix.sort_by {|o| o.path }.join(", ") %>
   <% end %><% end %>
-<% unless object.root? %>
-**Defined in:** <%= object.file ? object.file.sub(Dir.pwd, "") : "(unknown)" %>
-<% end %>
 
 <%= 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 %>
-# Public Class Methods
+# Class Methods
 <% pubmeths.each do |item| %>
 ## <%= item.name(false) %>(<%= item.parameters.map {|p| p.join(" ") }.join(", ") %>) [](#<%=aref(item)%>)
 <%= rdoc_to_md item.docstring %>
@@ -135,15 +124,15 @@ def serialize(object)
 
 <%= 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)%>) | <%= cnst.value %> |
-<% end %><% end %><% end %><% end %>',
+
+<% if (insmeths = public_instance_methods(object)).size > 0 %>
+# 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 %>',
       trim_mode: "<>",
     )
 
@@ -179,7 +168,7 @@ 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"
+      "**@#{tag.tag_name}** [#{tag.types&.join(', ')}] #{tag.text}\n\n"
     else
       ""
     end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: yard-markdown
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.5.0
 platform: ruby
 authors:
 - Stanislav (Stas) Katkov
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-12-16 00:00:00.000000000 Z
+date: 2024-12-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: yard
@@ -51,10 +50,14 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
-- example/Aquatic.md
-- example/Fish.md
-- example/Salmon.md
-- example/index.csv
+- example/rdoc/Bird.md
+- example/rdoc/Duck.md
+- example/rdoc/Waterfowl.md
+- example/rdoc/index.csv
+- example/yard/Aquatic.md
+- example/yard/Fish.md
+- example/yard/Salmon.md
+- example/yard/index.csv
 - example_rdoc.rb
 - example_yard.rb
 - lib/yard-markdown.rb
@@ -66,7 +69,6 @@ licenses:
 metadata:
   homepage_uri: https://poshtui.com
   source_code_uri: https://github.com/skatkov/yard-markdown
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -81,8 +83,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.9
-signing_key:
+rubygems_version: 3.6.2
 specification_version: 4
 summary: yard plugin to generate markdown documentation
 test_files: []

data/example/Aquatic.md

@@ -1,18 +0,0 @@
-# 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 |