docrb-html 0.2.5 → 0.3.0

data/lib/renderer/entities/container.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+class Renderer
+  module Entities
+    class Container < Base
+      attr_accessor :classes, :modules, :extends, :includes, :defs, :sdefs, :defined_by, :doc, :constants
+
+      def initialize(parent, model)
+        super(parent, model[:name])
+        @classes = init_entities(model, :classes, as: Class)
+        @modules = init_entities(model, :modules, as: Module)
+        @extends = init_references!(model, :extends)
+        @includes = init_references!(model, :includes)
+        @constants = model[:constants] || {}
+        @defs = model.fetch(:defs, {}).map { |k, v| Method.new(self, :def, k.to_s, v) }
+        @sdefs = model.fetch(:sdefs, {}).map { |k, v| Method.new(self, :sdef, k.to_s, v) }
+        @defined_by = init_entities(model, :defined_by, as: SourceDefinition)
+      end
+
+      def find_nested_container(named)
+        @modules.find { _1.name == named } || @classes.find { _1.name == named }
+      end
+
+      def resolve_class_path(path)
+        path.shift if path.first == "::"
+        obj = find_nested_container(path.shift)
+        return if obj.nil?
+
+        until path.empty?
+          obj = obj.find_nested_container(path.shift)
+          return if obj.nil?
+        end
+
+        obj
+      end
+
+      def init_entities(model, key, as:) = model.fetch(key, []).map { as.new(self, _1) }
+
+      def init_reference!(model, attr) = Reference.new(self, model, attr)
+
+      def init_references!(model, key, attr: nil)
+        model.fetch(key, []).map { init_reference!(_1, attr || key) }
+      end
+
+      def init_reference(model, attr)
+        return if model.nil?
+
+        Reference.new(self, model, attr)
+      end
+    end
+  end
+end

data/lib/renderer/entities/method.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+class Renderer
+  module Entities
+    class Method < Base
+      attr_accessor :overriding, :source, :definition
+
+      def initialize(parent, type, name, model)
+        super(parent, name)
+        @overriding = model[:overriding] # TODO
+        @type = type
+        @definition = MethodDefinition.new(self, model)
+      end
+
+      attr_reader :type
+    end
+  end
+end

data/lib/renderer/entities/method_argument.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+class Renderer
+  module Entities
+    class MethodArgument
+      attr_accessor :name, :type, :value, :value_type, :parent
+
+      def initialize(parent, arg)
+        @parent = parent
+        @name = arg[:name]
+        @type = arg[:type].to_sym
+        @value = arg[:value]
+        @value_type = arg[:value_type]
+      end
+
+      def positional? = type == :arg || type == :optarg
+
+      def optional? = type == :optarg || type == :kwoptarg
+
+      def kwarg? = type == :kwarg || type == :kwoptarg
+
+      def rest? = type == :restarg || type == :kwrestarg
+
+      def block? = type == :blockarg
+    end
+  end
+end

data/lib/renderer/entities/method_definition.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+class Renderer
+  module Entities
+    class MethodDefinition
+      attr_accessor :args, :defined_by, :doc, :name, :overridden_by, :visibility, :parent
+
+      def initialize(parent, model)
+        @parent = parent
+        @args = model[:definition][:args].map { MethodArgument.new(self, _1) }
+        @defined_by = SourceDefinition.new(nil, model[:definition][:defined_by])
+        @doc = model[:definition][:doc]
+        @name = model[:definition][:name]
+        @overridden_by = model[:definition][:overridden_by] # TODO
+        @visibility = model[:definition][:visibility].to_sym
+      end
+
+      def protected? = visibility == :protected?
+
+      def public? = visibility == :public?
+
+      def private? = visibility == :private?
+    end
+  end
+end

data/lib/renderer/entities/module.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+class Renderer
+  module Entities
+    class Module < Container
+      def type = :module
+
+      def initialize(parent, model)
+        if parent.nil?
+          as_root { super }
+        else
+          super
+        end
+      end
+
+      def resolve_references! = @references.each(&:resolve!)
+
+      private
+
+      def as_root
+        old_root = Entities.current_root
+        Entities.current_root = self
+        yield
+      ensure
+        Entities.current_root = old_root
+      end
+    end
+  end
+end

data/lib/renderer/entities/reference.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+class Renderer
+  module Entities
+    class Reference
+      def initialize(parent, model, field)
+        @parent = parent
+        @root = Entities.current_root
+        @root.register_reference(self)
+
+        if model.is_a? String
+          @name = model
+          @class_path = []
+        else
+          @name = model[:name]
+          @class_path = model[:class_path]
+        end
+        @field = field
+        @target = nil
+        @broken = false
+      end
+
+      def resolved? = !@target.nil? || @broken
+
+      def broken? = @broken
+
+      def resolve!
+        return __resolve_from_root__ if @class_path.first == "::"
+        return __resolve_from_class_path__ unless @class_path.empty?
+
+        location = __location__.dup
+        until location.empty?
+          container = location.shift.find_nested_container(@name)
+          return __assign__(container) if container
+        end
+
+        __assign__ @root.find_nested_container(@name)
+      end
+
+      def method_missing(name, *)
+        return @target.send(name, *) if @target.respond_to?(name)
+
+        return @name if name == :name
+
+        super
+      end
+
+      def respond_to_missing?(name, include_private = false)
+        @target&.respond_to_missing?(name, include_private) || super
+      end
+
+      def inspect
+        full_name = [@class_path, @name].flatten.join("::")
+        "#<#{self.class.name}:#{object_id_hex} #{broken? ? "broken" : "valid"} reference to #{full_name}>"
+      end
+
+      def to_s = inspect
+
+      private
+
+      def __location__
+        return @location if @location
+
+        parents = []
+        current = @parent.parent
+
+        while current&.parent
+          parents << current
+          current = current.parent
+        end
+
+        @location = parents
+      end
+
+      def __broken__
+        @broken = true
+        nil
+      end
+
+      def __assign__(target)
+        (@target = target) or __broken__
+      end
+
+      def __resolve_from_root__
+        container = @root.resolve_class_path(@class_path.dup) or return __broken__
+        __assign__ container.find_nested_container(@name)
+      end
+
+      def __resolve_from_class_path__
+        location = __location__.dup
+        container = nil
+
+        while !container && !location.empty? && !@class_path.empty?
+          container = location.shift&.find_nested_container(@class_path.first)
+        end
+        return __broken__ if container.nil?
+
+        container = container.resolve_class_path(@class_path[1..].dup) or return __broken__
+        __assign__ container.find_nested_container(@name)
+      end
+    end
+  end
+end

data/lib/renderer/entities/source_definition.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+class Renderer
+  module Entities
+    class SourceDefinition
+      attr_accessor :end_at, :start_at, :source, :markdown_source, :filename
+
+      def initialize(_parent, model)
+        @end_at = model[:end_at]
+        @start_at = model[:start_at]
+        @source = model[:source]
+        @markdown_source = model[:markdown_source]
+        @filename = model[:filename]
+      end
+    end
+  end
+end

data/lib/renderer/entities.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative "entities/base"
+require_relative "entities/container"
+
+require_relative "entities/method"
+require_relative "entities/method_argument"
+require_relative "entities/method_definition"
+require_relative "entities/module"
+require_relative "entities/class"
+require_relative "entities/source_definition"
+require_relative "entities/attribute"
+require_relative "entities/attribute_definition"
+require_relative "entities/reference"
+
+class Renderer
+  module Entities
+    def self.current_root = Thread.current[:current_root]
+
+    def self.current_root=(val)
+      Thread.current[:current_root] = val
+    end
+
+    def self.load_from(path)
+      model = JSON.load_file(path, symbolize_names: true)
+      Module.new(nil, model)
+        .tap(&:resolve_references!)
+    end
+  end
+end

data/lib/renderer/helpers.rb

@@ -1,26 +1,43 @@
 class Renderer
   class Helpers
+    class << self
+      attr_reader :current_renderer
+    end
+
+    class << self
+      attr_writer :current_renderer
+    end
+
     def svg(name, **kwargs)
       attrs = {}
       cls = kwargs.delete(:class_name)
-      attrs["class"] = cls if cls
+      title = kwargs.delete(:title)
+      attrs["class"] = cls if cls && !title
       kwargs.each { |k, v| attrs[k.to_s] = v.to_s }
 
       svg = File.read(Renderer::ASSETS_PATH.join("images/#{name}.svg"))
-      return svg if attrs.empty?
+      return svg if attrs.empty? && title.nil?
 
       doc = Nokogiri::XML svg
       attrs.each do |k, v|
         doc.css("svg")[0][k] = v
       end
-      doc.to_xml.split("\n").tap(&:shift).join("\n")
+      doc = doc.to_xml.split("\n").tap(&:shift).join("\n")
+      return doc if title.nil?
+
+      <<~HTML
+        <div class="svg-container #{cls}">
+            <div class="svg-title">#{title}</div>
+            #{doc}
+        </div>
+      HTML
     end
 
     def div(class_name, **kwargs, &block)
       classes = [class_name, kwargs.delete(:class_name)].flatten.compact
       args = kwargs
-             .compact
-             .map { |k, v| "#{k}=\"#{v.gsub(/"/, "\\\"")}\"" }
+        .compact
+        .map { |k, v| "#{k}=\"#{v.gsub('"', "\\\"")}\"" }
 
       start_tag = "<div class=\"#{classes.join(" ")}\" #{args.join(" ")}>"
       end_tag = "</div>"
@@ -31,10 +48,10 @@ class Renderer
       raw = block.call
 
       captured = if fake_buffer.empty?
-                   raw
-                 else
-                   fake_buffer
-                 end
+        raw
+      else
+        fake_buffer
+      end
     ensure
       block.binding.local_variable_set(:_erbout, "#{start_tag}#{captured}#{end_tag}")
     end
@@ -46,21 +63,21 @@ class Renderer
       raw = block.call
 
       captured = if fake_buffer.empty?
-                   raw
-                 else
-                   fake_buffer
-                 end
+        raw
+      else
+        fake_buffer
+      end
     ensure
       block.binding.local_variable_set(:_erbout, old_buffer)
     end
 
-    def git_url(source) = Renderer::Defs.singleton.git_url(source)
+    def git_url(source) = self.class.current_renderer.git_url(source)
 
-    def clean_file_path(source) = Renderer::Defs.singleton.clean_file_path(source)
+    def clean_file_path(source) = self.class.current_renderer.clean_file_path(source)
 
     def line_range(source)
-      from = source[:start_at]
-      to = source[:end_at]
+      from = source.line_start
+      to = source.line_end
 
       if from == to
         "line #{from}"
@@ -68,11 +85,52 @@ class Renderer
         "lines #{from} to #{to}"
       end
     end
+
+    def source_of(obj, parent = nil)
+      parent ||= obj.parent
+
+      case (v = parent.source_of(obj))
+      when :inherited, :included, :extended then v.to_s
+      when :self then ("override" if obj.try(:overriding))
+      else raise "WTF? Source of #{obj} is #{v.inspect}!"
+      end
+    end
+
+    def path_of(object, root: true)
+      return [] if object.nil? && !root
+      return [object.name] + path_of(object.parent, root: false) unless root
+
+      path = ["#{object.name}.html"] + path_of(object.parent, root: false)
+      path << ""
+      path.reverse.join("/")
+    end
+
+    def link_for(object)
+      case object
+      when Docrb::Parser::Attribute, Docrb::Parser::Method, Docrb::Parser::Constant
+        "#{path_of(object.parent)}##{anchor_for(object)}"
+      when Docrb::Parser::Class, Docrb::Parser::Module
+        path_of(object)
+      else
+        raise ArgumentError, "#link_for cannot link #{object.class.name}"
+      end
+    end
+
+    def anchor_for(object)
+      case object
+      when Docrb::Parser::Attribute then "#{object.type}-attr-#{object.name}"
+      when Docrb::Parser::Method then "#{object.type}-method-#{object.name}"
+      when Docrb::Parser::Constant then "const-#{object.name}"
+      when Docrb::Parser::Class, Docrb::Parser::Module then ""
+      else
+        raise ArgumentError, "#anchor_for cannot process #{object.class.name}"
+      end
+    end
   end
 
   Component.constants
-           .reject { _1 == :HELPERS }
-           .each do |cls|
+    .reject { _1 == :HELPERS }
+    .each do |cls|
     Helpers.define_method(cls.to_s.snakify) do |**kwargs|
       Component.const_get(cls).new(**kwargs).render
     end

data/lib/renderer/markdown.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+class Renderer
+  # Renderer provides a Redcarpet renderer with Rouge extensions
+  class MarkdownRenderer < Redcarpet::Render::HTML
+    def initialize(extensions = {})
+      super extensions.merge(link_attributes: { target: "_blank" })
+    end
+    include Rouge::Plugins::Redcarpet
+  end
+
+  # InlineRenderer provides a renderer for inline contents. This renderer
+  # does not emit paragraph tags.
+  class InlineRenderer < MarkdownRenderer
+    def paragraph(text)
+      text
+    end
+  end
+
+  # Markdown provides utilities for generating HTML from markdown contents
+  class Markdown
+    # Internal: Creates a new renderer based on a provided type by setting
+    # sensible defaults.
+    #
+    # type - Type of the renderer to be initialised. Use Renderer or
+    #        InlineRenderer
+    def self.make_render(type)
+      Redcarpet::Markdown.new(
+        type,
+        fenced_code_blocks: true,
+        autolink: true
+      )
+    end
+
+    # Renders a given input using the default renderer.
+    #
+    # input - Markdown content to be rendered
+    #
+    # Returns an HTML string containing the rendered Markdown content
+    def self.render(input)
+      make_render(MarkdownRenderer).render(input)
+    end
+
+    # Renders a given input using the inline renderer.
+    #
+    # input - Markdown content to be rendered
+    #
+    # Returns an HTML string containing the rendered Markdown content
+    def self.inline(input)
+      make_render(InlineRenderer).render(input)
+    end
+
+    # Renders a given Ruby source code into HTML
+    #
+    # source - Source code to be rendered
+    #
+    # Returns an HTML string containing the rendered source code
+    def self.render_source(source)
+      render("```ruby\n#{source}\n```")
+    end
+  end
+end

data/lib/renderer/metadata.rb

@@ -2,11 +2,7 @@
 
 class Renderer
   class Metadata
-    def initialize(base)
-      @data = JSON.parse(File.read("#{base}/metadata.json"))
-    end
-
-    def format_authors
+    def self.format_authors(authors)
       return nil if authors.nil? || authors.count.zero?
       return authors.first if authors.length == 1
 
@@ -14,31 +10,19 @@ class Renderer
       "#{authors.first}, and #{others} other#{others > 1 ? "s" : ""}"
     end
 
-    def project_links
+    def self.project_links(meta)
       links = []
-      links << { kind: "rubygems", href: host_url } if host_url
-
-      if git_url
-        links << if git_url.index("github.com/")
-                   { kind: "github", href: git_url }
-                 else
-                   { kind: "git", href: git_url }
-                 end
+      links << { kind: "rubygems", href: meta[:host_url] } if meta.key? :host_url
+
+      if meta.key? :git_url
+        links << if meta[:git_url].index("github.com/")
+          { kind: "github", href: meta[:git_url] }
+        else
+          { kind: "git", href: meta[:git_url] }
+        end
       end
 
       links
     end
-
-    def method_missing(method_name, *arguments, &)
-      if @data.include? method_name.to_s
-        @data[method_name.to_s]
-      else
-        super
-      end
-    end
-
-    def respond_to_missing?(method_name, include_private = false)
-      @data.key?(method_name.to_s) || super
-    end
   end
 end

data/lib/renderer/template.rb

@@ -1,5 +1,3 @@
-# frozen_string_literal: true
-
 class Renderer
   class Template
     class Bind
@@ -8,11 +6,11 @@ class Renderer
         @keys = keys
       end
 
-      def method_missing(method_name, *args, **kwargs, &)
+      def method_missing(method_name, ...)
         if @keys.include? method_name
           @keys[method_name]
         else
-          @obj.send(method_name, *args, **kwargs, &)
+          @obj.send(method_name, ...)
         end
       end
 
@@ -30,8 +28,8 @@ class Renderer
       @template.filename = path.to_s
     end
 
-    def render(b, *args, **kwargs)
-      bind = Bind.new(b, *args, **kwargs)
+    def render(bin, *, **)
+      bind = Bind.new(bin, *, **)
       @template.result(bind.make_binding)
     end
   end

data/lib/renderer/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 class Renderer
-  VERSION = "0.2.5"
+  VERSION = "0.3.0"
 end

data/script/makecomponent

@@ -4,7 +4,7 @@
 require_relative "../lib/renderer/core_extensions"
 name = ARGV.first.snakify
 real_name = ARGV.first
-dashed_name = name.gsub(/_/, "-")
+dashed_name = name.gsub("_", "-")
 File.write("assets/#{name}.scss", "div.#{dashed_name}-base {\n\n}\n")
 styles = File.read("assets/style.scss")
 File.write("assets/style.scss", "#{styles}@import './#{name}';\n")

data/templates/attribute.erb

@@ -0,0 +1,10 @@
+<div class="attribute-container"
+     data-origin="<%= source_of(item) %>"
+     data-type="attribute"
+     id="<%= kind %>-attr-<%= item.name %>"
+>
+    <%= attribute_display(item: item, kind:, omit_type:) %>
+    <div class="doc-block">
+        <%= documentation_block(doc: item.doc) %>
+    </div>
+</div>

data/templates/attribute_display.erb

@@ -0,0 +1,22 @@
+<% div("method-display-base", id:) do %>
+    <% if (dec = source_of(item)) %>
+        <%= svg(dec.to_s.downcase, class_name: "decoration", title: dec.to_s.capitalize) %>
+    <% end %>
+    <% if kind && !omit_type %>
+        <%= typedef(name: "#{kind.capitalize} Attribute") %>
+    <% end %>
+    <% name = capture do %>
+        <div class="container">
+            <div class="method-name"><%= item.name %></div>
+        </div>
+    <% end %>
+    <% if omit_link %>
+        <%= name %>
+    <% else %>
+        <a class="dashed" href="<%= link_for(item) %>"><%= name %></a>
+    <% end %>
+    <div class="label"><%= attr_type %></div>
+    <% if (visibility = item.doc&.dig(:meta, :visibility_annotation)) %>
+        <div class="label"><%= visibility %></div>
+    <% end %>
+<% end %>