yard-to_mkdocs 0.1.0

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

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+require 'yaml'
+
+include Helpers::ModuleHelper
+
+def init
+  options.serializer.basepath  = 'docs/yard_docs'
+  options.serializer.extension = 'md'
+
+  options.objects = objects = run_verifier(options.objects)
+
+  return serialize_onefile if options.onefile
+  options.files.each_with_index do |file, _i|
+    serialize_file(file, file.title)
+  end
+
+  options.delete(:objects)
+  options.delete(:files)
+
+  objects.each do |object|
+    begin
+      serialize(object)
+    rescue => e
+      path = options.serializer.serialized_path(object)
+      log.error "Exception occurred while generating '#{path}'"
+      log.backtrace(e)
+    end
+  end
+
+  mkdocs_file_path = File.expand_path('../../mkdocs.yml', options.serializer.basepath)
+  if File.exists?(mkdocs_file_path)
+    mkdocs_yaml = YAML.load_file(mkdocs_file_path)
+    mkdocs_nav = mkdocs_yaml['nav'].reject { |item| item["YARD Docs"] }
+    mkdocs_yaml['nav'] = mkdocs_nav + [{ "YARD Docs" => mkdocs_nav_tree(objects.first) }]
+    File.open(mkdocs_file_path, 'w') { |f| f.write(mkdocs_yaml.to_yaml) }
+  end
+end
+
+def mkdocs_nav_tree(current_object, current_path = "yard_docs")
+  return unless [:root, :class, :module].include?(current_object.type)
+
+  name = current_object.name
+  data = if current_object.children.any?
+    next_path = current_object.type == :root ? current_path : "#{current_path}/#{name}"
+    { name.to_s => ["#{current_path}/#{name}.md", *current_object.children.map { |child| mkdocs_nav_tree(child, next_path) }].compact }
+  else
+    { name.to_s => "#{current_path}/#{name}.md" }
+  end
+
+  if current_object.type == :root
+    data['root'][1..-1]
+  else
+    data
+  end
+end
+
+# Generate an HTML document for the specified object. This method is used by
+# most of the objects found in the Registry.
+# @param [CodeObject] object to be saved to HTML
+def serialize(object)
+  options.object = object
+  serialize_index(options) if object == '_index.md' && options.readme.nil?
+  Templates::Engine.with_serializer(object, options.serializer) do
+    T('layout').run(options)
+  end
+end
+
+# Generate the documentation output in one file (--one-file) which will load the
+# contents of all the javascript and css and output the entire contents without
+# depending on any additional files
+def serialize_onefile
+  Templates::Engine.with_serializer('index.md', options.serializer) do
+    T('onefile').run(options)
+  end
+end
+
+# Generate the index document for the output
+# @params [Hash] options contains data and flags that influence the output
+def serialize_index(options)
+  Templates::Engine.with_serializer('index.md', options.serializer) do
+    T('layout').run(options.merge(:index => true))
+  end
+end
+
+# Generate a single HTML file with the layout template applied. This is generally
+# the README file or files specified on the command-line.
+#
+# @param [File] file object to be saved to the output
+# @param [String] title currently unused
+#
+# @see layout#diskfile
+def serialize_file(file, title = nil) # rubocop:disable Lint/UnusedMethodArgument
+  options.object = Registry.root
+  options.file = file
+  # outfile = 'file.' + file.name + '.md'
+
+  serialize_index(options) if file == options.readme
+  # Templates::Engine.with_serializer(outfile, options.serializer) do
+  #   T('layout').run(options)
+  # end
+  options.delete(:file)
+end
+
+#
+# Generates a file to the output with the specified contents.
+#
+# @example saving a custom html file to the documentation root
+#
+#   asset('my_custom.md','## Custom File')
+#
+# @param [String] path relative to the document output where the file will be
+#   created.
+# @param [String] content the contents that are saved to the file.
+def asset(path, content)
+  if options.serializer
+    log.capture("Generating asset #{path}") do
+      options.serializer.serialize(path, content)
+    end
+  end
+end
+
+def menu_lists
+  Object.new.extend(T('layout')).menu_lists
+end
+
+# Generate a searchable method list in the output
+# @see ModuleHelper#prune_method_listing
+def generate_method_list; end
+
+# Generate a searchable class list in the output
+def generate_class_list; end
+
+# Generate a searchable file list in the output
+def generate_file_list; end
+
+def generate_list_contents; end
+
+# Generate the frame documentation in the output
+def generate_frameset; end
+
+# @api private
+class TreeContext
+  def initialize
+    @depth = 0
+    @even_odd = Alternator.new(:even, :odd)
+  end
+
+  def nest
+    @depth += 1
+    yield
+    @depth -= 1
+  end
+
+  # @return [String] Returns a css pixel offset, e.g. "30px"
+  def indent
+    "#{(@depth + 2) * 15}px"
+  end
+
+  def classes
+    classes = []
+    classes << 'collapsed' if @depth > 0
+    classes << @even_odd.next if @depth < 2
+    classes
+  end
+
+  class Alternator
+    def initialize(first, second)
+      @next = first
+      @after = second
+    end
+
+    def next
+      @next, @after = @after, @next
+      @after
+    end
+  end
+end
+
+# @return [String] HTML output of the classes to be displayed in the
+#    full_list_class template.
+def class_list(root = Registry.root, tree = TreeContext.new)
+  ""
+end

data/lib/yard/to_mkdocs/default/layout/dot/header.erb

@@ -0,0 +1,6 @@
+digraph yard {
+  graph [rankdir=BT rank=sink outputMode=nodesfirst packMode="graph" splines=true];
+  node [shape=record rank=sink rankType=sink];
+
+  <%= yieldall %>
+}

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

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+attr_reader :contents
+
+def init
+  if object
+    type = object.root? ? :module : object.type
+    sections :header, [T(type)]
+  else
+    sections :header, [:contents]
+  end
+end
+
+def header
+  tidy erb(:header)
+end

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

@@ -0,0 +1,3 @@
+# <%= options.title %>
+
+<%= yieldall %>

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

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

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

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+def init
+  @breadcrumb = []
+  @page_title = ''
+  @breadcrumb_title = ''
+  if @onefile
+    sections :layout
+  elsif defined?(@file) && @file
+    if @file.attributes[:namespace]
+      @object = options.object = Registry.at(@file.attributes[:namespace]) || Registry.root
+    end
+    @breadcrumb_title = "File: " + @file.title
+    @page_title = @breadcrumb_title
+    sections :layout, [:diskfile]
+  elsif @contents
+    sections :layout, [:contents]
+  else
+    case object
+    when '_index.md'
+      @page_title = options.title
+      sections :layout, [:index, [:listing, [:files, :objects]]]
+    when CodeObjects::Base
+      unless object.root?
+        cur = object.namespace
+        until cur.root?
+          @breadcrumb.unshift(cur)
+          cur = cur.namespace
+        end
+      end
+
+      @page_title = format_object_title(object)
+      type = object.root? ? :module : object.type
+      sections :layout, [T(type)]
+    end
+  end
+end
+
+attr_reader :contents
+
+def index
+  @objects_by_letter = {}
+  objects = Registry.all(:class, :module).sort_by {|o| o.name.to_s }
+  objects = run_verifier(objects)
+  objects.each {|o| (@objects_by_letter[o.name.to_s[0, 1].upcase] ||= []) << o }
+  erb(:index)
+end
+
+def layout
+  @path =
+    if !object || object.is_a?(String)
+      nil
+    elsif defined?(@file) && @file
+      @file.path
+    elsif !object.is_a?(YARD::CodeObjects::NamespaceObject)
+      object.parent.path
+    else
+      object.path
+    end
+
+  erb(:layout)
+end
+
+def diskfile
+  @file.attributes[:markup] ||= markup_for_file('', @file.filename)
+  data = htmlify(@file.contents, @file.attributes[:markup])
+  "<div id='filecontents'>" + data + "</div>"
+end
+
+# @return [Array<String>] core javascript files for layout
+# @since 0.7.0
+def javascripts
+  []
+end
+
+# @return [Array<String>] core stylesheets for the layout
+# @since 0.7.0
+def stylesheets
+  []
+end
+
+# @return [Array<Hash{Symbol=>String}>] the list of search links and drop-down menus
+# @since 0.7.0
+def menu_lists
+  [{:type => 'class', :title => 'Classes', :search_title => 'Class List'},
+    {:type => 'method', :title => 'Methods', :search_title => 'Method List'},
+    {:type => 'file', :title => 'Files', :search_title => 'File List'}]
+end

data/lib/yard/to_mkdocs/default/method/html/header.erb

@@ -0,0 +1,5 @@
+## Method: <%= object.path %>
+
+** Defined in:** <%= [object.file, *object.files].join(", ") %>
+
+<%= yieldall :index => 0 %>

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

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+def init
+  sections :header, [T('method_details')]
+end

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

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

data/lib/yard/to_mkdocs/default/method_details/html/header.erb

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

data/lib/yard/to_mkdocs/default/method_details/html/method_signature.erb

@@ -0,0 +1,9 @@
+### <% if object.tags(:overload).size == 1 %><%= signature(object.tag(:overload), false) %><% elsif object.tags(:overload).size > 1 %><% object.tags(:overload).each do |overload| %><%= signature(overload, false) %><% end %><% else %><%= signature(object, false) %><% end %>
+
+<% if object.aliases.size > 0 %>
+**Also known as:** <%= object.aliases.map(&:name).join(", ") %>
+<% end%>
+
+<% if owner != object.namespace %>
+_Originally defined in <%= object.namespace.type %>_
+<% end %>

data/lib/yard/to_mkdocs/default/method_details/html/source.erb

@@ -0,0 +1,5 @@
+
+** File '<%= object.file %>' <% if object.line %>, line <%= object.line %><% end %>**
+```ruby
+  <%= object.source %>
+```

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

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+def init
+  sections :header, [:method_signature, T('docstring'), :source]
+end
+
+def source
+  return if owner != object.namespace
+  return if Tags::OverloadTag === object
+  return if object.source.nil?
+  erb(:source)
+end

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

@@ -0,0 +1,10 @@
+<%= title_align_right format_object_title(object) %>
+
+<%= align_right "(Defined in: #{object.file})" %>
+<% if object.aliases.size > 0 %>
+
+<%= align_right "(Also known as: #{object.aliases.map {|o| o.name(true).to_s }.join(',')})" %>
+<% end %>
+
+<%= yieldall %>
+

data/lib/yard/to_mkdocs/default/method_details/text/method_signature.erb

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

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

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+def init
+  super
+  sections.last.pop
+end
+
+def format_object_title(object)
+  title = "Method: #{object.name(true)}"
+  title += " (#{object.namespace})" unless object.namespace.root?
+  title
+end

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

@@ -0,0 +1 @@
+<%= format_path object %> [label="{<%= yieldall.gsub("\n", '') %>}" rank=sink];

data/lib/yard/to_mkdocs/default/module/dot/dependencies.erb

@@ -0,0 +1,3 @@
+<% object.mixins(:instance).each do |obj| %>
+  <%= format_path object %> -> <%= format_path obj %> [style=dotted arrowType=none];
+<% end %>

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

@@ -0,0 +1,6 @@
+subgraph cluster_<%= format_path object %> {
+  label = "<%= h(object.name) unless object.path == "" %>"; labelloc=b;
+  <% for obj in @modules %>
+    <%= yieldall :object => obj %>
+  <% end %>
+}

data/lib/yard/to_mkdocs/default/module/dot/info.erb

@@ -0,0 +1,14 @@
+<%= object.type %> <%= h object.name %>
+<% if options.full %>
+|
+<% object.attributes.each do |scope, list| %>
+<% list.sort_by {|name, rw| name.to_s }.each do |name, rw| %>
+<%= uml_visibility(rw.values.compact.first) %> <%= h (rw[:read]||rw[:write]).name(true).gsub(/=$/,'') %> [<%= 'R' if rw[:read] %><%= 'W' if rw[:write] %>]\l
+<% end %>
+<% end %>
+|
+<% method_listing.each do |obj| %>
+<%= uml_visibility obj %> <%= h obj.name(true) %>
+<%= h(" : #{obj.tag(:return).types.first}") if obj.has_tag?(:return) && obj.tag(:return).types && obj.tag(:return).types.size > 0 %>\l
+<% end %>
+<% end %>

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

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+def init
+  @modules = object.children.select {|o| o.type == :module }
+  @classes = object.children.select {|o| o.type == :class }
+  sections :child, [:info], :classes, [T('class')], :header, [T('module')], :dependencies
+end
+
+def dependencies
+  return unless options.dependencies
+  erb(:dependencies)
+end
+
+def classes
+  @classes.map {|k| yieldall :object => k }.join("\n")
+end

data/lib/yard/to_mkdocs/default/module/html/attribute_details.erb

@@ -0,0 +1,7 @@
+<% scopes(attr_listing) do |list, scope| %>
+## <%= scope.to_s.capitalize %> Attribute Details
+
+<% list.each_with_index do |meth, i| %>
+<%= yieldall :object => meth, :owner => object, :index => i %>
+<% end %>
+<% end %>

data/lib/yard/to_mkdocs/default/module/html/attribute_summary.erb

@@ -0,0 +1,7 @@
+<% groups(attr_listing, "Attribute") do |list, name| %>
+## <%= name %>
+
+<% list.each do |meth| %>
+<%= yieldall :item => meth %>
+<% end %>
+<% end %>

data/lib/yard/to_mkdocs/default/module/html/box_info.erb

@@ -0,0 +1,14 @@
+<% if CodeObjects::ClassObject === object && object.superclass %>
+**Inherits:** <%= linkify 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 }.map {|o| linkify(o) }.join(", ") %>
+<% end %>
+<% end %>
+<% if (mixed_into = mixed_into(object)).size > 0 %>
+**Included in:** <%= mixed_into.sort_by {|o| o.path }.map {|o| linkify(o) }.join(", ") %>
+<% end %>
+<% unless object.root? %>
+**Defined in:** <%= erb(:defines) %>
+<% end %>

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

@@ -0,0 +1,7 @@
+## Defined Under Namespace
+
+<% @inner.each do |name, list| %>
+<% if list.size > 0 %>
+**<%= name.to_s.capitalize %>:** <%= list.map {|child| linkify(child, child.name(true)) }.join(", ") %>
+<% end %>
+<% end %>

data/lib/yard/to_mkdocs/default/module/html/constant_summary.erb

@@ -0,0 +1,13 @@
+<% if constant_listing.size > 0 %>
+<% groups(constant_listing, "Constant") do |list, name| %>
+## <%= name %>
+
+<% list.each do |cnst| %>
+<%= cnst.has_tag?(:deprecated) ? '~' : '' %><%= cnst.name %> = <%= yieldall :item => cnst %><%= cnst.has_tag?(:deprecated) ? '~' : '' %>
+
+```ruby
+  <%= cnst.value %>
+```
+<% end %>
+<% end %>
+<% end %>

data/lib/yard/to_mkdocs/default/module/html/defines.erb

@@ -0,0 +1 @@
+<%= [object.file || '(unknown)', *object.files.map(&:first)].join(', ') %>

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

@@ -0,0 +1 @@
+# <%= format_object_title(object) %><% if object.has_tag?(:abstract) %> Abstract<% end %><% if object.has_tag?(:deprecated) %> Deprecated<% end %><% if object.has_tag?(:api) && object.tag(:api).text == 'private' %> Private<% end %>

data/lib/yard/to_mkdocs/default/module/html/inherited_attributes.erb

@@ -0,0 +1,16 @@
+<% found_method = false %>
+<% inherited_attr_list do |superclass, attribs| %>
+<% if attr_listing.size == 0 && !found_method %>## Instance Attribute Summary<% end %>
+<% found_method = true %>
+### Attributes <%= superclass.type == :class ? 'inherited' : 'included' %> from <%= superclass %>
+
+<%=
+attribs.map do |method|
+  name = method.name(true).gsub(/=$/, '')
+  if superclass.type == :module && object.instance_mixins.include?(superclass)
+    name = "##{name}" unless name =~ /^#/
+  end
+  linkify(method, name)
+end.join(", ")
+%>
+<% end %>

data/lib/yard/to_mkdocs/default/module/html/inherited_constants.erb

@@ -0,0 +1,11 @@
+<% found_const = false %>
+<% inherited_constant_list do |superclass, consts| %>
+<% if constant_listing.size == 0 && !found_const %>
+## Constant Summary
+<% end %>
+<% found_const = true %>
+
+### Constants <%= superclass.type == :class ? 'inherited' : 'included' %>from <%= superclass %>
+
+<%= consts.map {|c| linkify c }.join(", ") %>
+<% end %>

data/lib/yard/to_mkdocs/default/module/html/inherited_methods.erb

@@ -0,0 +1,22 @@
+<% found_method = false %>
+<% object.inheritance_tree(true)[1..-1].each do |superclass| %>
+<% next if superclass.is_a?(YARD::CodeObjects::Proxy) %>
+<% next if options.embed_mixins.size > 0 && options.embed_mixins_match?(superclass) != false %>
+<% meths = prune_method_listing(superclass.meths(:included => false, :inherited => false)) %>
+<% meths.reject! {|m| object.child(:scope => m.scope, :name => m.name) != nil } %>
+<% meths.reject! {|m| m.is_alias? || m.is_attribute? } %>
+<% next if meths.size == 0 %>
+<% if method_listing.size == 0 && !found_method %>
+## Method Summary
+<% end %>
+<% found_method = true %>
+### Methods <%= superclass.type == :class ? 'inherited' : 'included' %> from <%= linkify superclass %>
+
+<%=
+meths.sort_by {|o| o.name.to_s }.map do |m|
+  name = m.name(true)
+  name = name.gsub(/^#/,'') if superclass.type == :module && object.class_mixins.include?(superclass)
+  linkify(m, name)
+end.join(", ")
+%>
+<% end %>

data/lib/yard/to_mkdocs/default/module/html/item_summary.erb

@@ -0,0 +1,16 @@
+* <% if @item.tags(:overload).size == 1 %><%= signature(@item.tag(:overload), true, false, !@item.attr_info) %><% else %><%= signature(@item, true, false, !@item.attr_info) %><% end %><% if @item.aliases.size > 0 %>(also: <%= @item.aliases.map {|o| h(o.name(true)) }.join(", ") %>)<% end %>
+<% if object != @item.namespace %><%= @item.namespace.type == :class ? 'inherited' : (@item.scope == :class ? 'extended' : 'included') %>from <%= linkify @item, object.relative_path(@item.namespace) %><% end %>
+<% if @item.constructor? %>constructor<% end %>
+<% if rw = @item.attr_info %>
+<% if !run_verifier([rw[:read]].compact).empty? && run_verifier([rw[:write]].compact).empty? %>readonly<% end %>
+<% if !run_verifier([rw[:write]].compact).empty? && run_verifier([rw[:read]].compact).empty? %>writeonly<% end %>
+<% end %>
+<% if @item.visibility != :public %><%= @item.visibility %><% end %>
+<% if @item.has_tag?(:abstract) %>abstract<% end %>
+<% if @item.has_tag?(:deprecated) %>deprecated<% end %>
+<% if @item.has_tag?(:api) && @item.tag(:api).text == 'private' %>private<% end %>
+<% if @item.has_tag?(:deprecated) %>
+**Deprecated.** <%= @item.tag(:deprecated).text %>
+<% else %>
+<%= docstring_summary(@item) %>
+<% end %>

data/lib/yard/to_mkdocs/default/module/html/method_details_list.erb

@@ -0,0 +1,7 @@
+<% scopes(method_listing(false)) do |list, scope| %>
+## <%= scope.to_s.capitalize %> Method Details
+
+<% list.each_with_index do |meth, i| %>
+<%= yieldall :object => meth, :owner => object, :index => i %>
+<% end %>
+<% end %>

data/lib/yard/to_mkdocs/default/module/html/method_summary.erb

@@ -0,0 +1,9 @@
+<% if method_listing.size > 0 %>
+<% groups(method_listing) do |list, name| %>
+## <%= name %>
+
+<% list.each do |meth| %>
+<%= yieldall :item => meth %>
+<% end %>
+<% end %>
+<% end %>

data/lib/yard/to_mkdocs/default/module/html/methodmissing.erb

@@ -0,0 +1,10 @@
+## Dynamic Method Handling
+
+This class handles dynamic methods through the `method_missing` method
+<% if @mm.namespace != object %>
+in the class <%= linkify @mm, @mm.namespace.path %>
+<% end %>
+
+<% if @mm.namespace == object %>
+<%= yieldall :object => @mm, :index => 0 %>
+<% end %>

data/lib/yard/to_mkdocs/default/module/html/pre_docstring.erb

@@ -0,0 +1 @@
+## Overview