yard-markdown 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9c561fb4adb1a813dee7cc4f1793ecee708627115f85aab396933822e4886cb0
-  data.tar.gz: 17e36c633008becd1b8ead5af645e58182d5be5959736cfb34280f4c7a077848
+  metadata.gz: 45d1e77bad42779c78eb819361eeef638e1eb6a6b622ef7f850298258a4cbf14
+  data.tar.gz: 715a1015c9d12f9ccdd13e9afe20f70e3b566dc9996161b8cedfcc7eecbcc9bf
 SHA512:
-  metadata.gz: 1c472b473610259d5067deceacbdc08ba3e2f68b00e07947d9b0aa55657623d28fccaf65237f213fc01f03b1f5d4674094fdfbe825f1829d17dadcc6c6efec69
-  data.tar.gz: abd879a66a9334c633120f9a1ee486cffa42dd4d08b184fe321bbea27a6f002a626b9adb76c46efc5637a3d489e3f365bdbea6b75f9901b3a22f8694bd73fbcc
+  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 --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/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 %>
@@ -96,7 +117,7 @@ def serialize(object)
   # <%= name %>
   <% list.each do |cnst| %>
   ## <%= cnst.name %> = [](#<%=aref(cnst)%>)
-  (<%= cnst.value %>) <%= cnst.docstring %>
+  <%= cnst.docstring %>
   <% end %>
 <% end %>
 
@@ -127,7 +148,9 @@ def serialize(object)
 
   <% end %>
 <% end %>
-  '.gsub(/^  /, ''), trim_mode: '%<>')
+  '.gsub(/^  /, ""),
+      trim_mode: "%<>",
+    )
 
   template.result(binding)
 end
@@ -150,10 +173,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 +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
 
@@ -193,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")
@@ -208,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.2.0
+  version: 0.2.1
 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