yard-to_mkdocs 0.1.0

data/lib/yard/to_mkdocs/default/module/setup.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+include Helpers::ModuleHelper
+
+def init
+  options.serializer.extension = 'md'
+  sections :header, :box_info, :pre_docstring, T('docstring'), :children,
+    :constant_summary, [T('docstring')], :inherited_constants,
+    :attribute_summary, [:item_summary], :inherited_attributes,
+    :method_summary, [:item_summary], :inherited_methods,
+    :methodmissing, [T('method_details')],
+    :attribute_details, [T('method_details')],
+    :method_details_list, [T('method_details')]
+end
+
+def pre_docstring
+  return if object.docstring.blank?
+  erb(:pre_docstring)
+end
+
+def children
+  @inner = [[:modules, []], [:classes, []]]
+  object.children.each do |child|
+    @inner[0][1] << child if child.type == :module
+    @inner[1][1] << child if child.type == :class
+  end
+  @inner.map! {|v| [v[0], run_verifier(v[1].sort_by {|o| o.name.to_s })] }
+  return if (@inner[0][1].size + @inner[1][1].size) == 0
+  erb(:children)
+end
+
+def methodmissing
+  mms = object.meths(:inherited => true, :included => true)
+  @mm = mms.find {|o| o.name == :method_missing && o.scope == :instance }
+  erb(:methodmissing) if @mm
+end
+
+def method_listing(include_specials = true)
+  return @smeths ||= method_listing.reject {|o| special_method?(o) } unless include_specials
+  return @meths if defined?(@meths) && @meths
+  @meths = object.meths(:inherited => false, :included => !options.embed_mixins.empty?)
+  unless options.embed_mixins.empty?
+    @meths = @meths.reject {|m| options.embed_mixins_match?(m.namespace) == false }
+  end
+  @meths = sort_listing(prune_method_listing(@meths))
+  @meths
+end
+
+def special_method?(meth)
+  return true if meth.name(true) == '#method_missing'
+  return true if meth.constructor?
+  false
+end
+
+def attr_listing
+  return @attrs if defined?(@attrs) && @attrs
+  @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
+  @attrs = sort_listing(@attrs)
+end
+
+def constant_listing
+  return @constants if defined?(@constants) && @constants
+  @constants = object.constants(:included => false, :inherited => false)
+  @constants += object.cvars
+  @constants = run_verifier(@constants)
+  @constants
+end
+
+def sort_listing(list)
+  list.sort_by {|o| [o.scope.to_s, o.name.to_s.downcase] }
+end
+
+def inherited_attr_list
+  object.inheritance_tree(true)[1..-1].each do |superclass|
+    next if superclass.is_a?(YARD::CodeObjects::Proxy)
+    next if !options.embed_mixins.empty? && options.embed_mixins_match?(superclass) != false
+    attribs = superclass.attributes[:instance]
+    attribs = attribs.select {|name, _rw| object.child(:scope => :instance, :name => name).nil? }
+    attribs = attribs.sort_by {|args| args.first.to_s }.map {|_n, m| m[:read] || m[:write] }
+    attribs = prune_method_listing(attribs, false)
+    yield superclass, attribs unless attribs.empty?
+  end
+end
+
+def inherited_constant_list
+  object.inheritance_tree(true)[1..-1].each do |superclass|
+    next if superclass.is_a?(YARD::CodeObjects::Proxy)
+    next if !options.embed_mixins.empty? && options.embed_mixins_match?(superclass) != false
+    consts = superclass.constants(:included => false, :inherited => false)
+    consts = consts.select {|const| object.child(:type => :constant, :name => const.name).nil? }
+    consts = consts.sort_by {|const| const.name.to_s }
+    consts = run_verifier(consts)
+    yield superclass, consts unless consts.empty?
+  end
+end
+
+def docstring_full(obj)
+  docstring = obj.tags(:overload).size == 1 && obj.docstring.empty? ?
+    obj.tag(:overload).docstring : obj.docstring
+
+  if docstring.summary.empty? && obj.tags(:return).size == 1 && obj.tag(:return).text
+    docstring = Docstring.new(obj.tag(:return).text.gsub(/\A([a-z])/, &:upcase).strip)
+  end
+
+  docstring
+end
+
+def docstring_summary(obj)
+  docstring_full(obj).summary
+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} Summary") }
+  else
+    yield(others, "#{type} Summary")
+  end
+end
+
+def scopes(list)
+  [:class, :instance].each do |scope|
+    items = list.select {|m| m.scope == scope }
+    yield(items, scope) unless items.empty?
+  end
+end
+
+def mixed_into(object)
+  unless globals.mixed_into
+    globals.mixed_into = {}
+    list = run_verifier Registry.all(:class, :module)
+    list.each {|o| o.mixins.each {|m| (globals.mixed_into[m.path] ||= []) << o } }
+  end
+
+  globals.mixed_into[object.path] || []
+end

data/lib/yard/to_mkdocs/default/module/text/children.erb

@@ -0,0 +1,10 @@
+Defined Under Namespace:
+------------------------
+
+<% @inner.each do |name, list| %>
+<% if list.size > 0 %>
+<% text = list.map {|c| c.name }.join(", ") + " (#{name})" %>
+<%= indent(wrap(text)) %>
+
+<% end %>
+<% end %>

data/lib/yard/to_mkdocs/default/module/text/class_meths_list.erb

@@ -0,0 +1,8 @@
+<% if class_meths.size > 0 %>
+Class methods:
+--------------
+
+<%= indent wrap(class_meths.map {|o| o.name.to_s }.join(", "), 68) %>
+
+
+<% end %>

data/lib/yard/to_mkdocs/default/module/text/extends.erb

@@ -0,0 +1,8 @@
+<% if object.mixins(:class).size > 0 %>
+Extended by:
+------------
+
+<%= indent wrap(object.mixins(:class).join(", "), 68) %>
+
+
+<% end %>

data/lib/yard/to_mkdocs/default/module/text/header.erb

@@ -0,0 +1,7 @@
+<%= title_align_right format_object_title(object) %>
+
+<%= yieldall %>
+
+<%= hr %>
+
+

data/lib/yard/to_mkdocs/default/module/text/includes.erb

@@ -0,0 +1,8 @@
+<% if object.mixins(:instance).size > 0 %>
+Includes:
+---------
+
+<%= indent wrap(object.mixins(:instance).join(", "), 68) %>
+
+
+<% end %>

data/lib/yard/to_mkdocs/default/module/text/instance_meths_list.erb

@@ -0,0 +1,8 @@
+<% if instance_meths.size > 0 %>
+Instance methods:
+-----------------
+
+<%= indent wrap(instance_meths.map {|o| o.name.to_s }.join(", "), 68) %>
+
+
+<% end %>

data/lib/yard/to_mkdocs/default/module/text/setup.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+def init
+  sections :header, [T('docstring')], :children, :includes, :extends,
+    :class_meths_list, :instance_meths_list
+end
+
+def class_meths
+  @classmeths ||= method_listing.select {|o| o.scope == :class }
+end
+
+def instance_meths
+  @instmeths ||= method_listing.select {|o| o.scope == :instance }
+end

data/lib/yard/to_mkdocs/default/onefile/html/files.erb

@@ -0,0 +1,6 @@
+<% @files.each do |file| %>
+<% @file = file %>
+## <%= file.title %>
+
+<%= diskfile %>
+<% end %>

data/lib/yard/to_mkdocs/default/onefile/html/layout.erb

@@ -0,0 +1,3 @@
+# <%= defined?(@title) ? @title : '' %>
+
+<%= yieldall %>

data/lib/yard/to_mkdocs/default/onefile/html/readme.erb

@@ -0,0 +1 @@
+<%= parse_top_comments_from_file %>

data/lib/yard/to_mkdocs/default/onefile/html/setup.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+include T('default/layout/html')
+include YARD::Parser::Ruby::Legacy
+
+def init
+  override_serializer
+  @object = YARD::Registry.root
+  @files.shift
+  @objects.delete(YARD::Registry.root)
+  @objects.unshift(YARD::Registry.root)
+  sections :layout, [:readme, :files, :all_objects]
+end
+
+def all_objects
+  @objects.map {|obj| obj.format(options) }.join("\n")
+end
+
+def layout
+  layout = Object.new.extend(T('layout'))
+  @css_data = layout.stylesheets.map {|sheet| read_asset(sheet) }.join("\n")
+  @js_data = layout.javascripts.map {|script| read_asset(script) }.join("")
+
+  erb(:layout)
+end
+
+def read_asset(file)
+  file = T('fulldoc').find_file(file)
+  return unless file
+  data = File.read(file)
+  superfile = self.class.find_nth_file('fulldoc', 2)
+  data.gsub!('{{{__super__}}}', superfile ? IO.read(superfile) : "")
+  data
+end
+
+private
+
+def parse_top_comments_from_file
+  return unless defined?(@readme) && @readme
+  return @readme.contents unless @readme.filename =~ /\.rb$/
+  data = ""
+  tokens = TokenList.new(@readme.contents)
+  tokens.each do |token|
+    break unless token.is_a?(RubyToken::TkCOMMENT) || token.is_a?(RubyToken::TkNL)
+    data += (token.text[/\A#\s{0,1}(.*)/, 1] || "\n")
+  end
+  YARD::Docstring.new(data)
+end
+
+def override_serializer
+  return if @serializer.nil?
+  class << @serializer
+    define_method(:serialize) do |object, data|
+      return unless object == 'index.md'
+      super(object, data)
+    end
+
+    define_method(:serialized_path) do |object|
+      return object if object.is_a?(String)
+      'index.md'
+    end
+  end
+end

data/lib/yard/to_mkdocs/default/root/dot/child.erb

@@ -0,0 +1,3 @@
+<% if inner = yieldall.gsub("\n", '') %>
+Root [label="{<%= inner %>}" rank=sink];
+<% end %>

data/lib/yard/to_mkdocs/default/root/dot/setup.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+include T('default/module/dot')
+
+def format_path(_object)
+  ""
+end

data/lib/yard/to_mkdocs/default/root/html/setup.rb

@@ -0,0 +1,2 @@
+# frozen_string_literal: true
+include T('default/module/html')

data/lib/yard/to_mkdocs/default/tags/html/example.erb

@@ -0,0 +1,13 @@
+<% if object.has_tag?(:example) %>
+Examples:
+
+<% object.tags(:example).each do |tag| %>
+<% unless tag.name.empty? %>
+<%= tag.name %>
+
+<% end %>
+```ruby
+  <%= tag.text %>
+```
+<% end %>
+<% end %>

data/lib/yard/to_mkdocs/default/tags/html/index.erb

@@ -0,0 +1,2 @@
+
+<%= yieldall %>

data/lib/yard/to_mkdocs/default/tags/html/option.erb

@@ -0,0 +1,13 @@
+<% if object.has_tag?(:option) %>
+<% object.parameters.each do |param, default| %>
+<% tags = object.tags(:option).select {|x| x.name.to_s == param.to_s.sub(/^\*+|:$/, '') } %>
+<% next if tags.empty? %>
+
+Options Hash (`<%= param %>`):
+
+<% tags.each do |tag| %>
+* <%= tag.pair.name %> <%= format_types(tag.pair.types || ['Object']) %> <% if tag.pair.defaults %> - default: <%= tag.pair.defaults.map { |t| "`#{h t}`" }.join(", ") %><% end %> <% if tag.pair.text && tag.pair.text =~ /\S/ %> - <%= tag.pair.text %><% end %>
+
+<% end %>
+<% end %>
+<% end %>

data/lib/yard/to_mkdocs/default/tags/html/overload.erb

@@ -0,0 +1,11 @@
+<% if object.tags(:overload).size == 1 %>
+<%= yieldall :object => object.tag(:overload) %>
+<% elsif object.has_tag?(:overload) && object.tags(:overload).any? {|o| !o.docstring.blank? } %>
+
+Overloads:
+
+<% object.tags(:overload).each do |overload| %>
+<% next if overload.docstring.blank? %>
+* <%= signature(overload, false, false) %> <%= yieldall :object => overload %>
+<% end %>
+<% end %>

data/lib/yard/to_mkdocs/default/tags/html/see.erb

@@ -0,0 +1,7 @@
+<% if object.has_tag?(:see) %>
+See Also:
+
+<% for tag in object.tags(:see) %>
+* <%= linkify(tag.name, tag.text) %></li>
+<% end %>
+<% end %>

data/lib/yard/to_mkdocs/default/tags/html/tag.erb

@@ -0,0 +1,6 @@
+<%= (defined?(@label) && @label) ? @label : YARD::Tags::Library.labels[@name] %>:
+
+<% object.tags(@name).each do |tag| %>
+* <% unless @no_names %><%= h tag.name %><% end %> <% unless @no_types %><%= format_types(tag.types) %><% end %> <% if @name == :param && (o=object.parameters.find {|a| [tag.name.to_s, tag.name.to_s + ":"].include?(a[0]) }) && o[1] %>_(defaults to: `<%= h o[1] %>`)_<% end %> <% if tag.text && !tag.text.empty? %><% unless (@no_types || tag.types.nil? || tag.types.empty?) && @no_names %>&mdash;<% end %><%= tag.text %><% end %>
+
+<% end %>

data/lib/yard/to_mkdocs/default/tags/setup.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+def init
+  tags = Tags::Library.visible_tags - [:abstract, :deprecated, :note, :todo]
+  create_tag_methods(tags - [:example, :option, :overload, :see])
+  sections :index, tags.map {|t| t.to_s.tr('.', '_').to_sym }
+  sections.any(:overload).push(T('docstring'))
+end
+
+def return
+  if object.type == :method
+    return if object.constructor?
+    return if object.tags(:return).size == 1 && object.tag(:return).types == ['void']
+  end
+  tag(:return)
+end
+
+def param
+  tag(:param) if object.type == :method
+end
+
+private
+
+def tag(name, opts = nil)
+  return unless object.has_tag?(name)
+  opts ||= options_for_tag(name)
+  @no_names = opts[:no_names] ? true : false
+  @no_types = opts[:no_types] ? true : false
+  @name = name
+  out = erb('tag')
+  @no_names = nil
+  @no_types = nil
+  out
+end
+
+def create_tag_methods(tags)
+  tags.each do |tag|
+    tag_meth = tag.to_s.tr('.', '_')
+    next if respond_to?(tag_meth)
+    instance_eval(<<-eof, __FILE__, __LINE__ + 1)
+      def #{tag_meth}; tag(#{tag.inspect}) end
+    eof
+  end
+end
+
+def options_for_tag(tag)
+  opts = {:no_types => true, :no_names => true}
+  case Tags::Library.factory_method_for(tag)
+  when :with_types
+    opts[:no_types] = false
+  when :with_types_and_name
+    opts[:no_types] = false
+    opts[:no_names] = false
+  when :with_name
+    opts[:no_names] = false
+  end
+  opts
+end

data/lib/yard/to_mkdocs/default/tags/text/example.erb

@@ -0,0 +1,12 @@
+<% if object.has_tag?(:example) %>
+
+Examples:
+---------
+
+<% object.tags(:example).each_with_index do |tag, i| %>
+<%= indent("# " + tag.name + "\n") if tag.name %>
+<%= indent(format_source(tag.text)) + "\n" %>
+<%= "\n" if i < object.tags(:example).size - 1 %>
+<% end %>
+<% end %>
+

data/lib/yard/to_mkdocs/default/tags/text/index.erb

@@ -0,0 +1 @@
+<%= yieldall %>

data/lib/yard/to_mkdocs/default/tags/text/option.erb

@@ -0,0 +1,20 @@
+<% if object.has_tag?(:option) %>
+<% object.parameters.each do |param, default| %>
+<% tags = object.tags(:option).select {|x| x.name.to_s == param.to_s.sub(/^\*+|:$/, '') } %>
+<% next if tags.empty? %>
+Options Hash (<%= param %>):
+--------------<%= hr(param.to_s.length) %>--
+
+<% for tag in tags %>
+<% text = "" %>
+<% text += format_types(tag.pair.types || ['Object']) %>
+<% text += " " + tag.pair.name.to_s %>
+<% if tag.pair.defaults %>
+<% text += " - default: " + tag.pair.defaults.join(", ") %>
+<% end %>
+<% text += " - " + tag.pair.text if tag.pair.text %>
+<%= indent(wrap(text)) %>
+
+<% end %>
+<% end %>
+<% end %>

data/lib/yard/to_mkdocs/default/tags/text/overload.erb

@@ -0,0 +1,19 @@
+<% if object.tags(:overload).size == 1 %>
+<%= wrap(yieldall(:object => object.tag(:overload))) %>
+<% elsif object.has_tag?(:overload) %>
+Overloads:
+----------
+
+<% object.tags(:overload).each do |overload| %>
+<% if overload.tags.size > 0 %>
+<%= hr %>
+
+<%= indent signature(overload) %>
+
+<%= hr %>
+
+<%= indent(wrap(yieldall(:object => overload))) %>
+
+<% end %>
+<% end %>
+<% end %>

data/lib/yard/to_mkdocs/default/tags/text/see.erb

@@ -0,0 +1,11 @@
+<% if object.has_tag?(:see) %>
+See Also:
+---------
+
+<% for tag in object.tags(:see) %>
+<% text = "- " + tag.name %>
+<% text += " - " + tag.text if tag.text && !tag.text.empty? %>
+<%= indent(wrap(text)) %>
+<% end %>
+<% end %>
+

data/lib/yard/to_mkdocs/default/tags/text/tag.erb

@@ -0,0 +1,13 @@
+<% title = (defined?(@label) && @label) ? @label : YARD::Tags::Library.labels[@name] %>
+<%= title %>:
+<%= hr(title.length) %>-
+
+<% object.tags(@name).each do |tag| %>
+<% text = "" %>
+<% text += format_types(tag.types) + " " unless @no_types || tag.types.nil? %>
+<% text += tag.name.to_s + " " unless @no_names %>
+<% text += "- " unless @no_names && @no_types %>
+<% text += tag.text if tag.text && !tag.text.empty? %>
+<%= indent wrap(text) %>
+
+<% end %>

data/lib/yard/to_mkdocs/version.rb

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

data/lib/yard-to_mkdocs.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'yard'
+require 'yard/to_mkdocs/version'
+
+module YARD
+  module Serializers
+    class FileSystemSerializer < Base
+      def initialize(opts = {})
+        super
+        @name_map = nil
+        @basepath = (options[:basepath] || 'doc').to_s
+        @extension = 'md'
+      end
+    end
+  end
+end
+
+YARD::Templates::Engine.register_template_path File.expand_path('./yard/to_mkdocs', __dir__)

data/yard-to_mkdocs.gemspec

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative "lib/yard/to_mkdocs/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "yard-to_mkdocs"
+  spec.version       = YARD::ToMkdocs::VERSION
+  spec.authors       = ["Octothope"]
+  spec.email         = ["octothorpe@invoca.com"]
+
+  spec.summary       = "Simple template that removes extra frames from yardocs html template"
+  spec.description   = spec.summary
+  spec.homepage      = "https://github.com/invoca/yard-to_mkdocs"
+  spec.license       = "MIT"
+  spec.required_ruby_version = ">= 2.6.0"
+
+  spec.metadata["allowed_push_host"] = "https://rubygems.org"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (f == __FILE__) || f.match(%r{\A(?:(?:test|spec|features)/|\.(?:git|travis|circleci)|appveyor)})
+    end
+  end
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "yard"
+
+  # For more information and examples about making a new gem, checkout our
+  # guide at: https://bundler.io/guides/creating_gem.html
+end