yard-markdown 0.1.2 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f8bc0dd303b8e3b40e53d55a7b53c339e8d0c8c8f8a44427c12bc6cca9f303f4
-  data.tar.gz: 13159d5918456cbfa5e909679ba2596a52dfecb24ec14bdccac20f51d5552146
+  metadata.gz: 45d1e77bad42779c78eb819361eeef638e1eb6a6b622ef7f850298258a4cbf14
+  data.tar.gz: 715a1015c9d12f9ccdd13e9afe20f70e3b566dc9996161b8cedfcc7eecbcc9bf
 SHA512:
-  metadata.gz: e2aa7fac3e51b28d2bece0f852da3436d9f9bdb83242af7f78bb25aefde514206f01fe6f9d70f2765b6342cf11b1b40a484454b782565161ec50a72705c41aec
-  data.tar.gz: 37c63aa190abaa091d27c279268a23756f120393a519286983510933e5fd22f9076cc6c8f8b694ba25e27d4b638b5d44587f5528c9a97c61f4db3e2b861cca70
+  metadata.gz: c813cfeaad842d55c9b4573fa91f025ac07d78b8bb512a45f32af671a25c213d34e4291c6346ab0e43e141fab89dd82ba5ca279760e17b4ac06a1f042c39fd26
+  data.tar.gz: 4080476f10d33d9d98c39ca2d04e4834c2a1ef8308451ad102022991286f88e4f42bba1fbdf5ddac53a1c16ad3cb40fa53eb656b72d59d5155a6e6ea589db4d6

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` parameter.
+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

@@ -8,7 +8,7 @@
 The base class for all birds.
 
 # Constants
-## DEFAULT_DUCK_VELOCITY =
+## DEFAULT_DUCK_VELOCITY = [](#constant-DEFAULT_DUCK_VELOCITY)
 (70) Default velocity for a flying duck.
 
 

data/example/Duck.md

@@ -21,7 +21,7 @@ Features:
    * swim
 
 # Constants
-## DEFAULT_DUCK_VELOCITY =
+## DEFAULT_DUCK_VELOCITY = [](#constant-DEFAULT_DUCK_VELOCITY)
 (70) Default velocity for a flying duck.
 
 

data/example/Waterfowl.md

@@ -7,7 +7,7 @@
 A mixin for waterfowl creatures.
 
 # Constants
-## DEFAULT_DUCK_VELOCITY =
+## DEFAULT_DUCK_VELOCITY = [](#constant-DEFAULT_DUCK_VELOCITY)
 (70) Default velocity for a flying duck.
 
 

data/example/index.csv

@@ -0,0 +1,18 @@
+name,type,path
+Waterfowl,Module,Waterfowl.md
+DEFAULT_DUCK_VELOCITY,Constant,Waterfowl.md#constant-DEFAULT_DUCK_VELOCITY
+swim,Method,Waterfowl.md#method-i-swim
+Bird,Class,Bird.md
+DEFAULT_DUCK_VELOCITY,Constant,Bird.md#constant-DEFAULT_DUCK_VELOCITY
+_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
+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

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,19 +21,79 @@ 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}'"
       log.backtrace(e)
     end
   end
+
+  serialize_index(objects)
+end
+
+def serialize_index(objects)
+  filepath = "#{options.serializer.basepath}/index.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)]
+      elsif object.type == :module
+        csv << [object.name, "Module", options.serializer.serialized_path(object)]
+      end
+
+      if constant_listing.size.positive?
+        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 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 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 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 %>
@@ -56,8 +116,8 @@ def serialize(object)
 <% groups(constant_listing, "Constants") do |list, name| %>
   # <%= name %>
   <% list.each do |cnst| %>
-  ## <%= cnst.name %> =
-  (<%= cnst.value %>) <%= cnst.docstring %>
+  ## <%= cnst.name %> = [](#<%=aref(cnst)%>)
+  <%= cnst.docstring %>
   <% end %>
 <% end %>
 
@@ -88,13 +148,17 @@ def serialize(object)
 
   <% end %>
 <% end %>
-  '.gsub(/^  /, ""), trim_mode: "%<>")
+  '.gsub(/^  /, ""),
+      trim_mode: "%<>",
+    )
 
   template.result(binding)
 end
 
 def aref(object)
-  if !object.attr_info.nil?
+  if object.type == :constant
+    "constant-#{object.name(false)}"
+  elsif !object.attr_info.nil?
     "attribute-#{object.scope[0]}-#{object.name(false)}"
   else
     "#{object.type}-#{object.scope[0]}-#{object.name(false)}"
@@ -103,15 +167,17 @@ end
 
 def constant_listing
   return @constants if defined?(@constants) && @constants
+
   @constants = object.constants(included: false, inherited: false)
   @constants += object.cvars
   @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)
@@ -124,18 +190,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
 
@@ -151,7 +218,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")
@@ -166,13 +233,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.1.2
+  version: 0.2.1
 platform: ruby
 authors:
 - Stanislav (Stas) Katkov
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-11-28 00:00:00.000000000 Z
+date: 2024-01-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: yard
@@ -24,7 +24,7 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: yard theme plugin that generates markdown documentation for gems
+description: yard plugin to generates markdown documentation for gems
 email:
 - yard-markdown@skatkov.com
 executables: []
@@ -32,7 +32,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".editorconfig"
-- ".standard.yml"
+- ".streerc"
 - ".yardopts"
 - LICENSE.txt
 - README.md
@@ -41,6 +41,7 @@ files:
 - example/Bird.md
 - example/Duck.md
 - example/Waterfowl.md
+- example/index.csv
 - lib/yard-markdown.rb
 - sig/yard/markdown.rbs
 - templates/default/fulldoc/markdown/setup.rb
@@ -65,8 +66,8 @@ 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 theme plugin that generates markdown documentation for gems
+summary: yard plugin to generate markdown documentation
 test_files: []

data/.standard.yml

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