yard-markdown 0.2.0 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9c561fb4adb1a813dee7cc4f1793ecee708627115f85aab396933822e4886cb0
-  data.tar.gz: 17e36c633008becd1b8ead5af645e58182d5be5959736cfb34280f4c7a077848
+  metadata.gz: 336637063b30cdb36819afce2e0380f467c1763ebbb022b006317488edebe134
+  data.tar.gz: 73692c82e184b6e3b7259af0ba1ce74fea209b71a56ed089c611ac0035415bbd
 SHA512:
-  metadata.gz: 1c472b473610259d5067deceacbdc08ba3e2f68b00e07947d9b0aa55657623d28fccaf65237f213fc01f03b1f5d4674094fdfbe825f1829d17dadcc6c6efec69
-  data.tar.gz: abd879a66a9334c633120f9a1ee486cffa42dd4d08b184fe321bbea27a6f002a626b9adb76c46efc5637a3d489e3f365bdbea6b75f9901b3a22f8694bd73fbcc
+  metadata.gz: e9b0c05b3cfef30f77040ea8542091dd99231cece58f912079c0e356042bfe99fbfd4aad80e509bdad0390f07cc23d0a4be133db8d4c67e33981556cea87bbfd
+  data.tar.gz: c32c66c335f301dcaec541401b7d1276267aa5054b29574f70d8d1697680dddae6d649b044ce934df88ee4372efbbe2cb45e9eb6570aea6b0a465f77c91e57a4

data/.streerc

@@ -0,0 +1,2 @@
+--print-width=100
+--plugins=plugin/trailing_comma,disable_ternary

data/README.md

@@ -1,25 +1,32 @@
 # Yard::Markdown
 
-Yard theme plugin that generates markdown documentation for gems
+Yard plugin to generate markdown documentation
 
 ## Goals:
 - Compatible with Github Flavored Markdown
-- Mimick yard html layout in markdown format as much as possible
+- 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
-Add these lines:
+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 'yard-markdown'
+gem install yard-markdown
 ```
-And run `bundle install`
 
-Run yardoc with `--format=markdown --plugin=markdown` parameters.
+Run `yardoc --format=markdown` to generate markdown documentation.
 
 ## Backstory
-Successor to rdoc-mardown gem that was authored by me. So there is a lot of similarities between two - [example](https://github.com/skatkov/rdoc-markdown/tree/main/example).
-
-This gem is used by documentation reviewing tool called [POSH TUI](https://poshtui.com)
+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).
 
 ## Testing
 Unit tests can't really test this gem properly. So it's semi-manual process of making changes and reviewing output.

data/Rakefile

@@ -9,6 +9,8 @@ Rake::TestTask.new(:test) do |t|
   t.test_files = FileList["test/**/test_*.rb"]
 end
 
-require "standard/rake"
+require "syntax_tree/rake_tasks"
+SyntaxTree::Rake::CheckTask.new
+SyntaxTree::Rake::WriteTask.new
 
-task default: %i[test standard]
+task default: %i[test stree:write]

data/example/Bird.md

@@ -4,18 +4,17 @@
 | **Inherits:** | Object  |
 | **Defined in:**    | example.rb    |
 
-
 The base class for all birds.
-
 # Constants
-## DEFAULT_DUCK_VELOCITY = [](#constant-DEFAULT_DUCK_VELOCITY)
-(70) Default velocity for a flying duck.
-
+## DEFAULT_DUCK_VELOCITY [](#constant-DEFAULT_DUCK_VELOCITY)
+Default velocity for a flying duck.
+## DEFAULT_SPEED [](#constant-DEFAULT_SPEED)
+Maximum speed for a swimming duck.
 
 # Public Instance Methods
-## _fly_impl(_direction , _velocity ) [](#method-i-_fly_impl)
+## _fly_impl(_direction, _velocity) [](#method-i-_fly_impl)
 :nodoc:
-## fly(direction , velocity ) [](#method-i-fly)
+## fly(direction, velocity) [](#method-i-fly)
 Fly somewhere.
 
 Flying is the most critical feature of birds.

data/example/Duck.md

@@ -6,7 +6,6 @@
 | **Includes:** | Waterfowl |
 | **Defined in:**    | example.rb    |
 
-
 A duck is a Waterfowl Bird.
 
 Features:
@@ -19,14 +18,14 @@ Features:
  waterfowl::
 
    * swim
-
 # Constants
-## DEFAULT_DUCK_VELOCITY = [](#constant-DEFAULT_DUCK_VELOCITY)
-(70) Default velocity for a flying duck.
-
+## DEFAULT_DUCK_VELOCITY [](#constant-DEFAULT_DUCK_VELOCITY)
+Default velocity for a flying duck.
+## DEFAULT_SPEED [](#constant-DEFAULT_SPEED)
+Maximum speed for a swimming duck.
 
 # Public Instance Methods
-## initialize(domestic , rubber ) [](#method-i-initialize)
+## initialize(domestic, rubber) [](#method-i-initialize)
 Creates a new duck.
 ## speak() [](#method-i-speak)
 Duck overrides generic implementation.

data/example/Waterfowl.md

@@ -3,13 +3,12 @@
 | -----------------:  | :-----    |
 | **Defined in:**    | example.rb    |
 
-
 A mixin for waterfowl creatures.
-
 # Constants
-## DEFAULT_DUCK_VELOCITY = [](#constant-DEFAULT_DUCK_VELOCITY)
-(70) Default velocity for a flying duck.
-
+## DEFAULT_DUCK_VELOCITY [](#constant-DEFAULT_DUCK_VELOCITY)
+Default velocity for a flying duck.
+## DEFAULT_SPEED [](#constant-DEFAULT_SPEED)
+Maximum speed for a swimming duck.
 
 # Public Instance Methods
 ## swim() [](#method-i-swim)

data/example/index.csv

@@ -1,14 +1,17 @@
 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

data/example.rb

@@ -131,6 +131,8 @@ end
 
 # Default velocity for a flying duck.
 DEFAULT_DUCK_VELOCITY = 70
+DEFAULT_SPEED = 10 # Maximum speed for a swimming duck.
+
 
 # Default rubber duck.
 #

data/lib/yard-markdown.rb

@@ -7,4 +7,4 @@ module YARD
   end
 end
 
-YARD::Templates::Engine.register_template_path File.dirname(__FILE__) + '/../templates'
+YARD::Templates::Engine.register_template_path File.dirname(__FILE__) + "/../templates"

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

@@ -3,11 +3,11 @@
 # https://github.com/lsegal/yard/blob/2d197a381c5d4cc5c55b2c60fff992b31c986361/docs/CodeObjects.md
 
 require "erb"
+require "csv"
 
-def init
-  # here I need to copy README.md if there is one.
-  # I also need to write index.md files
+include Helpers::ModuleHelper
 
+def init
   options.objects = objects = run_verifier(options.objects)
 
   options.delete(:objects)
@@ -21,9 +21,7 @@ def init
     next if object.name == :root
 
     begin
-      Templates::Engine.with_serializer(object, options.serializer) do
-        serialize(object)
-      end
+      Templates::Engine.with_serializer(object, options.serializer) { serialize(object) }
     rescue => e
       path = options.serializer.serialized_path(object)
       log.error "Exception occurred while generating '#{path}'"
@@ -34,45 +32,68 @@ def init
   serialize_index(objects)
 end
 
-
-require 'csv'
-
 def serialize_index(objects)
   filepath = "#{options.serializer.basepath}/index.csv"
 
-  CSV.open(filepath, 'wb') do |csv|
+  CSV.open(filepath, "wb") do |csv|
     csv << %w[name type path]
 
     objects.each do |object|
       next if object.name == :root
 
       if object.type == :class
-        csv << [object.name, 'Class', options.serializer.serialized_path(object)]
+        csv << [object.name, "Class", options.serializer.serialized_path(object)]
       elsif object.type == :module
-        csv << [object.name, 'Module', options.serializer.serialized_path(object)]
+        csv << [object.name, "Module", options.serializer.serialized_path(object)]
       end
 
       if constant_listing.size.positive?
-        constant_listing.each { |cnst| csv << [cnst.name(false), 'Constant', (options.serializer.serialized_path(object) + "#" +aref(cnst))] }
+        constant_listing.each do |cnst|
+          csv << [
+            cnst.name(false),
+            "Constant",
+            (options.serializer.serialized_path(object) + "#" + aref(cnst)),
+          ]
+        end
       end
 
       if (insmeths = public_instance_methods(object)).size > 0
-        insmeths.each { |item| csv << [item.name(false), 'Method', options.serializer.serialized_path(object) + "#" + aref(item)] }
+        insmeths.each do |item|
+          csv << [
+            item.name(false),
+            "Method",
+            options.serializer.serialized_path(object) + "#" + aref(item),
+          ]
+        end
       end
 
       if (pubmeths = public_class_methods(object)).size > 0
-        pubmeths.each { |item| csv << [item.name(false), 'Method', options.serializer.serialized_path(object) + '#' + aref(item)]}
+        pubmeths.each do |item|
+          csv << [
+            item.name(false),
+            "Method",
+            options.serializer.serialized_path(object) + "#" + aref(item),
+          ]
+        end
       end
 
       if (attrs = attr_listing(object)).size > 0
-        attrs.each { |item| csv << [item.name(false), 'Attribute', options.serializer.serialized_path(object) + "#" + aref(item)]}
+        attrs.each do |item|
+          csv << [
+            item.name(false),
+            "Attribute",
+            options.serializer.serialized_path(object) + "#" + aref(item),
+          ]
+        end
       end
     end
   end
 end
 
 def serialize(object)
-  template = ERB.new('# <%= format_object_title object %>
+  template =
+    ERB.new(
+      '# <%= format_object_title object %>
 | | |
 | -----------------:  | :-----    |
 <% if CodeObjects::ClassObject === object && object.superclass %>
@@ -87,25 +108,23 @@ def serialize(object)
   | **Defined in:**    | <%= object.file ? object.file : "(unknown)" %>    |
 <% end %>
 
-
 <%= object.docstring %>
 
-
 <% if constant_listing.size > 0 %>
 <% groups(constant_listing, "Constants") do |list, name| %>
   # <%= name %>
   <% list.each do |cnst| %>
-  ## <%= cnst.name %> = [](#<%=aref(cnst)%>)
-  (<%= cnst.value %>) <%= cnst.docstring %>
+  ## <%= cnst.name %> [](#<%=aref(cnst)%>)
+  <%= cnst.docstring %>
+
   <% end %>
 <% end %>
-
 <% end %>
 
 <% 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)%>)
+  ## <%= item.name(false) %>(<%= item.parameters.map {|p| p.join("") }.join(", ")%>) [](#<%=aref(item)%>)
   <%= item.docstring %>
 
   <% end %>
@@ -127,7 +146,9 @@ def serialize(object)
 
   <% end %>
 <% end %>
-  '.gsub(/^  /, ''), trim_mode: '%<>')
+  '.gsub(/^  /, ""),
+      trim_mode: "%<>",
+    )
 
   template.result(binding)
 end
@@ -150,10 +171,11 @@ def constant_listing
   @constants
 end
 
-include Helpers::ModuleHelper
-
 def public_method_list(object)
-  prune_method_listing(object.meths(inherited: false, visibility: [:public]), included: false).sort_by { |m| m.name.to_s }
+  prune_method_listing(
+    object.meths(inherited: false, visibility: [:public]),
+    included: false,
+  ).sort_by { |m| m.name.to_s }
 end
 
 def public_class_methods(object)
@@ -166,18 +188,19 @@ end
 
 def attr_listing(object)
   @attrs = []
-  object.inheritance_tree(true).each do |superclass|
-    next if superclass.is_a?(CodeObjects::Proxy)
-    next if !options.embed_mixins.empty? &&
-            !options.embed_mixins_match?(superclass)
-    [:class, :instance].each do |scope|
-      superclass.attributes[scope].each do |_name, rw|
-        attr = prune_method_listing([rw[:read], rw[:write]].compact, false).first
-        @attrs << attr if attr
+  object
+    .inheritance_tree(true)
+    .each do |superclass|
+      next if superclass.is_a?(CodeObjects::Proxy)
+      next if !options.embed_mixins.empty? && !options.embed_mixins_match?(superclass)
+      %i[class instance].each do |scope|
+        superclass.attributes[scope].each do |_name, rw|
+          attr = prune_method_listing([rw[:read], rw[:write]].compact, false).first
+          @attrs << attr if attr
+        end
       end
+      break if options.embed_mixins.empty?
     end
-    break if options.embed_mixins.empty?
-  end
   sort_listing @attrs
 end
 
@@ -193,7 +216,7 @@ def generate_method_list
 end
 
 def sort_listing(list)
-  list.sort_by {|o| [o.scope.to_s, o.name.to_s.downcase] }
+  list.sort_by { |o| [o.scope.to_s, o.name.to_s.downcase] }
 end
 
 def groups(list, type = "Method")
@@ -208,13 +231,7 @@ def groups(list, type = "Method")
   else
     others = []
     group_data = {}
-    list.each do |itm|
-      if itm.group
-        (group_data[itm.group] ||= []) << itm
-      else
-        others << itm
-      end
-    end
+    list.each { |itm| itm.group ? (group_data[itm.group] ||= []) << itm : others << itm }
     group_data.each { |group, items| yield(items, group) unless items.empty? }
   end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: yard-markdown
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.2
 platform: ruby
 authors:
 - Stanislav (Stas) Katkov
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-12-05 00:00:00.000000000 Z
+date: 2024-01-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: yard
@@ -32,7 +32,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".editorconfig"
-- ".standard.yml"
+- ".streerc"
 - ".yardopts"
 - LICENSE.txt
 - README.md
@@ -66,7 +66,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.22
+rubygems_version: 3.5.4
 signing_key:
 specification_version: 4
 summary: yard plugin to generate markdown documentation

data/.standard.yml

@@ -1,3 +0,0 @@
-# For available configuration options, see:
-#   https://github.com/testdouble/standard
-ruby_version: 2.6