yard-markdown 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6ff780c12b0efc36b1ba7c766ac4a8645d5fa9c5776e6ac1351a064b797e4fd1
+  data.tar.gz: fb42ed6ee07c97cd22af57267b0aed1570b7fb9fe89a4840a643fe4858d4a2a5
+SHA512:
+  metadata.gz: d0ff4417bb45236c042daece82cf8442840d0f9c573a6be70e513c5c603ca813dc07ce8d30a5ddad0707463d95e9ac8a548f3f476bde5b777aaf4a27d16e91dd
+  data.tar.gz: 9687a9283bd08e6b5be2d00f0da4f2c41b997a71ef2875c0090aa15ccc78f0ea77d1710b9aba5b63775f2c34efe58dacc668adf9ded49453cbc9a1e575eb04ed

data/.editorconfig

@@ -0,0 +1,13 @@
+# top-most EditorConfig file
+root = true
+
+# Unix-style newlines with a newline ending every file
+# Two spaces for indenting
+[*]
+end_of_line = lf
+insert_final_newline = true
+indent_style = space
+indent_size = 2
+charset = utf-8
+trim_trailing_whitespace = true
+max_line_length = 120

data/.standard.yml

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

data/.yardopts

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

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2023 Stanislav Katkov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,14 @@
+# Yard::Markdown
+
+Yard-markdown produces markdown documents for ruby gems.
+
+Goals:
+- Compatible with Github Flavored Markdown
+- Mimick yard html layout in markdown format as much as possible
+- Produce .csv index file alonside markdown documentation
+
+This is a successor to rdoc-mardown gem, so it will very likely be similar to this [example](https://github.com/skatkov/rdoc-markdown/tree/main/example).
+
+
+Testing:
+  `yardoc example.rb` -> outputs everything into doc.

data/Rakefile

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/test_*.rb"]
+end
+
+require "standard/rake"
+
+task default: %i[test standard]

data/example/Bird.md

@@ -0,0 +1,36 @@
+# Class: Bird
+| | |
+| -----------------:  | :-----    |
+| **Inherits:** | Object  |
+| **Defined in:**    | example.rb    |
+
+
+The base class for all birds.
+
+# Constants
+## DEFAULT_DUCK_VELOCITY =
+(70) Default velocity for a flying duck.
+
+
+# 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+?
+++

data/example/Duck.md

@@ -0,0 +1,48 @@
+# 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
+
+# Constants
+## DEFAULT_DUCK_VELOCITY =
+(70) Default velocity for a flying duck.
+
+
+# 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.

data/example/Waterfowl.md

@@ -0,0 +1,17 @@
+# Module: Waterfowl
+| | |
+| -----------------:  | :-----    |
+| **Defined in:**    | example.rb    |
+
+
+A mixin for waterfowl creatures.
+
+# Constants
+## DEFAULT_DUCK_VELOCITY =
+(70) Default velocity for a flying duck.
+
+
+# Public Instance Methods
+## swim() [](#method-i-swim)
+Swimming helper.
+

data/example.rb

@@ -0,0 +1,145 @@
+##
+# === RDoc::Generator::Markdown example.
+#
+# This example employs various RDoc features to demonstrate
+# generator output.
+#
+# ---
+#
+# Links:
+#
+#  1. {Project Home Page}[https://github.com/skatkov/rdoc-markdown)
+#  2. {RDoc Documentation}[http://ruby-doc.org/stdlib-2.0.0/libdoc/rdoc/rdoc/RDoc/Markup.html]
+#
+
+##
+# A mixin for waterfowl creatures.
+module Waterfowl
+  # Swimming helper.
+  def swim
+    puts "swimming around"
+  end
+end
+
+##
+# The base class for all birds.
+class Bird
+  ##
+  # Produce some noise.
+  #--
+  # FIXME: maybe extract this to a base class +Animal+?
+  #++
+  def speak # :yields: text
+    puts "generic tweeting"
+    yield "tweet"
+    yield "tweet"
+  end
+
+  # 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)
+  def fly(direction, velocity)
+    _fly_impl(direction, velocity)
+  end
+
+  def _fly_impl(_direction, _velocity) # :nodoc:
+    puts "flying away: direction=#{direction}, velocity=#{velocity}"
+  end
+end
+
+##
+# A duck is a Waterfowl Bird.
+#
+# Features:
+#
+#  bird::
+#
+#    * speak
+#    * fly
+#
+#  waterfowl::
+#
+#    * swim
+class Duck
+  extend Animal
+  include Waterfowl
+
+  # :section: Bird overrides
+
+  # Duck overrides generic implementation.
+  def speak
+    speech = quack
+    yield speech
+  end
+
+  # Implements quacking
+  def quack
+    "quack"
+  end
+
+  private :quack
+
+  # :section: Duck extensions
+
+  # True for domestic ducks.
+  attr_accessor :domestic
+
+  # True for rubber ducks.
+  attr_reader :rubber
+
+  MAX_VELOCITY = 130 # Maximum velocity for a flying duck.
+
+  ##
+  # Global list of all rubber ducks.
+  #
+  # Use when in trouble.
+  @@rubber_ducks = []
+
+  # @return [Array<Duck>] list of all rubber ducks
+  def self.rubber_ducks
+    @@rubber_ducks
+  end
+
+  # Creates a new duck.
+  #
+  # @param [Boolean] domestic
+  # @param [Boolean] rubber
+  def initialize(domestic, rubber)
+    @domestic = domestic
+    @rubber = rubber
+    @@rubber_ducks << self if rubber
+  end
+
+  # Checks if this duck is a useful one.
+  #
+  # :call-seq:
+  #   Bird.useful? -> bool
+  def useful?
+    @domestic || @rubber
+  end
+end
+
+# Default velocity for a flying duck.
+DEFAULT_DUCK_VELOCITY = 70
+
+# Default rubber duck.
+#
+# *Note:*
+#  Global variables are evil, but rubber ducks are worth it.
+$default_rubber_duck = Duck.new(false, true)
+
+# Domestic rubber duck.
+#
+# *Note:*
+#  This is weird... Thus not making it global.
+domestic_rubber_duck = Duck.new(true, true) # rubocop:disable Lint/UselessAssignment

data/lib/yard/markdown/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module YARD
+  module Markdown
+    VERSION = "0.1.0"
+  end
+end

data/lib/yard/markdown.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require "yard"
+require_relative "markdown/version"
+require_relative "serializers/markdown_serializer"
+
+module YARD
+  module Markdown
+    YARD::Templates::Engine.register_template_path "/../../templates"
+  end
+end

data/lib/yard/serializers/markdown_serializer.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module YARD
+  module Serializers
+    class MarkdownSerializer < YARD::Serializers::FileSystemSerializer
+      def initialize(opts = {})
+        super(opts.merge(extension: "md"))
+      end
+    end
+  end
+end

data/sig/yard/markdown.rbs

@@ -0,0 +1,6 @@
+module Yard
+  module Markdown
+    VERSION: String
+    # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+  end
+end

data/templates/default/fulldoc/markdown/content.erb

@@ -0,0 +1,2 @@
+# Test
+<%= @object.docstring %>

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

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+# https://github.com/lsegal/yard/blob/2d197a381c5d4cc5c55b2c60fff992b31c986361/docs/CodeObjects.md
+
+require_relative "../../../../lib/yard/serializers/markdown_serializer"
+require "erb"
+
+def init
+  # here I need to copy README.md if there is one.
+  # I also need to write index.md files
+
+  options.objects = objects = run_verifier(options.objects)
+
+  options.delete(:objects)
+  options.delete(:files)
+
+  options.serializer.extension = "md"
+
+  generate_method_list
+
+  objects.each do |object|
+    next if object.name == :root
+
+    begin
+      Templates::Engine.with_serializer(object, options.serializer) do
+        serialize(object)
+      end
+    rescue => e
+      path = options.serializer.serialized_path(object)
+      log.error "Exception occurred while generating '#{path}'"
+      log.backtrace(e)
+    end
+  end
+end
+
+def serialize(object)
+  template = ERB.new('# <%= format_object_title object %>
+| | |
+| -----------------:  | :-----    |
+<% if CodeObjects::ClassObject === object && object.superclass %>
+  | **Inherits:** | <%= object.superclass %>  |
+<% end %>
+<% [[:class, "Extended by"], [:instance, "Includes"]].each do |scope, name| %>
+  <% 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 : "(unknown)" %>    |
+<% end %>
+
+
+<%= object.docstring %>
+
+
+<% if constant_listing.size > 0 %>
+<% groups(constant_listing, "Constants") do |list, name| %>
+  # <%= name %>
+  <% list.each do |cnst| %>
+  ## <%= cnst.name %> =
+  (<%= cnst.value %>) <%= 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.docstring %>
+
+  <% end %>
+<% end %>
+
+<% if (pubmeths = public_class_methods(object)).size > 0 %>
+  # Public Class Methods
+  <% pubmeths.each do |item| %>
+  ## <%= item.name(false) %>(<%= item.parameters.map {|p| p.join(" ") }.join(", ") %>) [](#<%=aref(item)%>)
+  <%= item.docstring %>
+
+  <% end %>
+<% end %>
+<% if (attrs = attr_listing(object)).size > 0 %>
+  # Attributes
+  <% attrs.each do |item|%>
+  ## <%= item.name %><%= item.reader? ? "[RW]" : "[R]" %> [](#<%=aref(item)%>)
+  <%= item.docstring %>
+
+  <% end %>
+<% end %>
+  '.gsub(/^  /, ""), trim_mode: "%<>")
+
+  template.result(binding)
+end
+
+def aref(object)
+  if !object.attr_info.nil?
+    "attribute-#{object.scope[0]}-#{object.name(false)}"
+  else
+    "#{object.type}-#{object.scope[0]}-#{object.name(false)}"
+  end
+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 }
+end
+
+def public_class_methods(object)
+  public_method_list(object).select { |o| o.scope == :class }
+end
+
+def public_instance_methods(object)
+  public_method_list(object).select { |o| o.scope == :instance }
+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
+      end
+    end
+    break if options.embed_mixins.empty?
+  end
+  sort_listing @attrs
+end
+
+def generate_method_list
+  @items = prune_method_listing(Registry.all(:method), false)
+  @items = @items.reject { |m| m.name.to_s =~ /=$/ && m.is_attribute? }
+  @items = @items.sort_by { |m| m.name.to_s }
+
+  # @list_title = "Method List"
+  # @list_type = "method"
+  # generate_list_contents
+  # binding.irb
+end
+
+def sort_listing(list)
+  list.sort_by {|o| [o.scope.to_s, o.name.to_s.downcase] }
+end
+
+def groups(list, type = "Method")
+  groups_data = object.groups
+  if groups_data
+    list.each { |m| groups_data |= [m.group] if m.group && owner != m.namespace }
+    others = list.select { |m| !m.group || !groups_data.include?(m.group) }
+    groups_data.each do |name|
+      items = list.select { |m| m.group == name }
+      yield(items, name) unless items.empty?
+    end
+  else
+    others = []
+    group_data = {}
+    list.each do |itm|
+      if itm.group
+        (group_data[itm.group] ||= []) << itm
+      else
+        others << itm
+      end
+    end
+    group_data.each { |group, items| yield(items, group) unless items.empty? }
+  end
+
+  return if others.empty?
+  if others.first.respond_to?(:scope)
+    scopes(others) { |items, scope| yield(items, "#{scope.to_s.capitalize} #{type}") }
+  else
+    yield(others, type)
+  end
+end

metadata

@@ -0,0 +1,61 @@
+--- !ruby/object:Gem::Specification
+name: yard-markdown
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Stanislav (Stas) Katkov
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2023-11-26 00:00:00.000000000 Z
+dependencies: []
+description: yard-markdown is a yard plugin template to generate markdown files
+email:
+- yard-markdown@skatkov.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".editorconfig"
+- ".standard.yml"
+- ".yardopts"
+- LICENSE.txt
+- README.md
+- Rakefile
+- example.rb
+- example/Bird.md
+- example/Duck.md
+- example/Waterfowl.md
+- lib/yard/markdown.rb
+- lib/yard/markdown/version.rb
+- lib/yard/serializers/markdown_serializer.rb
+- sig/yard/markdown.rbs
+- templates/default/fulldoc/markdown/content.erb
+- templates/default/fulldoc/markdown/setup.rb
+homepage: https://poshtui.com
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://poshtui.com
+  source_code_uri: https://github.com/skatkov/yard-markdown
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.6.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.20
+signing_key:
+specification_version: 4
+summary: yard-markdown is a yard plugin template to generate markdown files
+test_files: []