docrb-html 0.2.5 → 0.3.0

data/lib/docrb-html.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+require "json"
+
+require "erb"
+require "sassc"
+require "nokogiri"
+require "redcarpet"
+require "rouge"
+require "rouge/plugins/redcarpet"
+
+require_relative "renderer/version"
+require_relative "renderer/core_extensions"
+require_relative "renderer/markdown"
+
+class Renderer
+  ASSETS_PATH = Pathname.new(__dir__).join("../assets")
+  TEMPLATES_PATH = Pathname.new(__dir__).join("../templates")
+  STYLE_BASE = SassC::Engine.new(File.read(ASSETS_PATH.join("style.scss")),
+    style: :compressed,
+    load_paths: [ASSETS_PATH]).render
+end
+
+require_relative "renderer/template"
+require_relative "renderer/component"
+require_relative "renderer/helpers"
+require_relative "renderer/page"
+require_relative "renderer/metadata"
+require_relative "renderer/entities"
+
+class Renderer
+  def now = Time.now.strftime("%A, %-d %b %Y %H:%M:%S %Z")
+
+  def output_path(*args) = File.join(@output, *args.map(&:to_s))
+
+  def initialize(source, spec, output)
+    @output = output
+    @footer = Component::Footer.new(version: VERSION, updated_at: now)
+    @spec = spec
+    @source = source
+    Helpers.current_renderer = self
+  end
+
+  def git_url(loc)
+    url = @spec[:git_url]
+    tip = @spec[:git_tip]
+    filename = clean_file_path(loc)
+    "#{url}/blob/#{tip}#{filename}#L#{loc.line_start}"
+  end
+
+  def clean_file_path(definition) = definition.file_path.gsub(@spec[:git_root], "")
+
+  def make_outline
+    (@source.nodes.by_kind(:module) + @source.nodes.by_kind(:class))
+      .map { outline(_1) }
+  end
+
+  def outline(object, level = 0)
+    {
+      level:,
+      object:,
+      classes: object.classes.map { outline(_1, level + 1) },
+      modules: object.modules.map { outline(_1, level + 1) }
+    }
+  end
+
+  def render
+    project_header = Component::ProjectHeader.new(
+      name: @spec[:name],
+      description: @spec[:summary],
+      license: @spec[:license],
+      owner: Metadata.format_authors(@spec[:authors]),
+      links: Metadata.project_links(@spec)
+    )
+
+    index = Page.new(title: "#{@spec[:name]} - Docrb") do
+      readme = Component::Markdown.new(source: Markdown.render(@spec[:readme]))
+
+      [
+        project_header,
+        Component::TabBar.new(
+          selected_index: 0,
+          items: [
+            { name: "Readme", href: "/" },
+            { name: "Components", href: "/components.html" }
+          ]
+        ),
+        readme,
+        @footer
+      ]
+    end
+
+    components = Page.new(title: "Components - #{@spec[:name]} - Docrb") do
+      [
+        project_header,
+        Component::TabBar.new(
+          selected_index: 1,
+          items: [
+            { name: "Readme", href: "/" },
+            { name: "Components", href: "/components.html" }
+          ]
+        ),
+        Component::ComponentList.new(list: make_outline),
+        @footer
+      ]
+    end
+
+    pages(@source.nodes.by_kind(:class, :module))
+
+    FileUtils.mkdir_p @output
+
+    index.render_to(output_path("index.html"))
+    components.render_to(output_path("components.html"))
+    File.write(output_path("style.css"), STYLE_BASE)
+
+    copy_assets
+  end
+
+  def copy_assets
+    [
+      "js/filtering.js",
+      "favicon.ico"
+    ].each do |file|
+      File.write(output_path(File.basename(file)),
+        File.read(ASSETS_PATH.join(file)))
+    end
+  end
+
+  def pages(comps, parents = [])
+    comps.each do |comp|
+      title = "#{comp.name} - #{@spec[:name]} - Docrb"
+      page = Page.new(title:, level: parents.count) do
+        [
+          Component::ClassHeader.new(
+            type: comp.kind,
+            name: comp.name,
+            definitions: comp.defined_by.map do |by|
+              {
+                filename: File.basename(by.file_path),
+                git_url: git_url(by)
+              }
+            end
+          ),
+          Component::Breadcrumb.new(
+            project_name: @spec[:name],
+            items: (parents + [comp]).map.with_index do |p, idx|
+              { name: p.name, parents: parents[0...idx].map(&:name) }
+            end
+          ),
+          Component::DocBox.new(
+            item: comp,
+            meta: @spec
+          ),
+          @footer
+        ]
+      end
+
+      parent_dir = output_path(*parents.map(&:name))
+      FileUtils.mkdir_p(parent_dir)
+      page.render_to(File.join(parent_dir, "#{comp.name}.html"))
+
+      pages(comp.classes + comp.modules, parents + [comp])
+    end
+  end
+end

data/lib/renderer/component/attribute.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+class Renderer
+  class Component
+    class Attribute < Component
+      prop :item, :kind, :omit_type
+    end
+  end
+end

data/lib/renderer/component/attribute_display.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+class Renderer
+  class Component
+    class AttributeDisplay < Component
+      prop :item, :attr_type, :omit_link, :kind, :omit_type
+
+      def prepare
+        @attr_type = case item.type
+        when :accessor then "read/write"
+        when :reader then "read-only"
+        else "write-only"
+        end
+      end
+    end
+  end
+end

data/lib/renderer/component/constant_display.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+class Renderer
+  class Component
+    class ConstantDisplay < Component
+      prop :item, :omit_link
+    end
+  end
+end

data/lib/renderer/component/doc_box.rb

@@ -3,32 +3,40 @@
 class Renderer
   class Component
     class DocBox < Component
-      prop :item, :meta, :defs, :has_class_docs, :has_class_details, :has_attrs,
-           :has_class_methods, :has_instance_methods, :page_components,
-           :defs, :sdefs, :attrs
+      prop :item, :meta, :has_class_docs, :has_class_details,
+        :instance_methods, :has_instance_methods,
+        :class_methods, :has_class_methods,
+        :has_instance_attributes, :instance_attributes,
+        :has_class_attributes, :class_attributes,
+        :has_constants, :constants,
+        :page_components
 
       def prepare
-        @item = defs.specialized_projection.find_path(@item)
+        @has_class_docs = (item.doc && !item.doc.empty?) || false
+        @instance_methods = item.all_instance_methods
+        @class_methods = item.all_class_methods
+        @instance_attributes = item.kind == :class ? item.all_instance_attributes : []
+        @class_attributes = item.all_class_attributes
+        @constants = item.constants
 
-        @has_class_docs = item[:doc] && !item[:doc].empty?
-        @defs = item.defs || []
-        @sdefs = item.sdefs || []
-        @attrs = item.attributes || []
-
-        @has_attrs = !@attrs.empty?
-        @has_class_methods = !@sdefs.empty?
-        @has_instance_methods = !@defs.empty?
+        @has_instance_attributes = !@instance_attributes.empty?
+        @has_class_attributes = !@class_attributes.empty?
+        @has_class_methods = !@class_methods.empty?
+        @has_instance_methods = !@instance_methods.empty?
         @has_class_details =
-          !item[:inherits].nil? \
-          || !item.fetch(:extends, []).empty? \
-          || !item.fetch(:includes, []).empty? \
-          || !item.fetch(:modules, []).empty? \
-          || !item.fetch(:classes, []).empty?
+          (item.kind == :class && !item.inherits.nil?) \
+            || !item.extends.empty? \
+            || !item.includes.empty? \
+            || !item.modules.empty? \
+            || !item.classes.empty?
+        @has_constants = !@constants.empty?
 
         @page_components = {
           "class-documentation" => { enabled: has_class_docs, name: "Class Documentation" },
           "class-details" => { enabled: has_class_details, name: "Inheritance" },
-          "attributes" => { enabled: has_attrs, name: "Attributes" },
+          "constants" => { enabled: has_constants, name: "Constants" },
+          "class-attributes" => { enabled: has_class_attributes, name: "Class Attributes" },
+          "instance-attributes" => { enabled: has_instance_attributes, name: "Instance Attributes" },
           "class-methods" => { enabled: has_class_methods, name: "Class Methods" },
           "instance-methods" => { enabled: has_instance_methods, name: "Instance Methods" }
         }

data/lib/renderer/component/documentation_comment.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+class Renderer
+  class Component
+    class DocumentationComment < Component
+      prop :doc, :class_name
+    end
+  end
+end

data/lib/renderer/component/field_block.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+class Renderer
+  class Component
+    class FieldBlock < Component
+      prop :fields
+    end
+  end
+end

data/lib/renderer/component/method_argument.rb

@@ -3,9 +3,14 @@
 class Renderer
   class Component
     class MethodArgument < Component
-      prop :type, :name, :value, :value_type, :computed
+      prop :type, :name, :value, :value_type, :computed, :arg
 
       def prepare
+        @type = @arg.kind
+        @name = @arg.name
+        @value = @arg.value&.source
+        @value_type = @arg.value_type
+
         @computed = {
           rest: rest_arg,
           name:,
@@ -15,17 +20,17 @@ class Renderer
       end
 
       def continuation_for_type
-        if type == "kwarg" || type == "kwoptarg"
+        if arg.keyword? && !arg.rest?
           :colon
-        elsif type&.index("opt")&.zero?
+        elsif arg.optional?
           :equal
         end
       end
 
       REST_ARG_BY_TYPE = {
-        "kwrestarg" => :double,
-        "restarg" => :single,
-        "blockarg" => :block
+        kwrest: :double,
+        rest: :single,
+        block: :block
       }.freeze
 
       def rest_arg
@@ -36,71 +41,22 @@ class Renderer
         return if value_type.nil?
 
         case value_type
-        when "sym"
+        when :symbol, :bool
           { kind: :symbol, value: }
-        when "bool"
-          { kind: :symbol, value: value.inspect }
-        when "nil"
+        when :nil
           { kind: :symbol, value: "nil" }
-        when "int"
+        when :number
           { kind: :number, value: }
-        when "str"
+        when :string
           { kind: :string, value: }
-        when "send"
-          method_call_argument(value)
-        when "const"
-          const_value(value)
+        when :call
+          { kind: :call, value: }
+        when :const
+          { kind: :const, value: [value] }
         else
           { kind: :plain, value: }
         end
       end
-
-      def method_call_argument(value)
-        class_path = value[:target].map do |i|
-          next { kind: :symbol, value: "self" } if i == "self"
-
-          # TODO: Is this plain?
-          [{ kind: :class_or_module, value: i }, { kind: :plain, value: "::" }]
-        end.flatten
-
-        class_path.pop
-
-        {
-          kind: :method_call_argument,
-          value: [
-            class_path,
-            { kind: :plain, value: "." },
-            { kind: :plain, value: value[:name] }
-          ].flatten
-        }
-      end
-
-      def const_value(value)
-        class_path = value[:target].map do |i|
-          # TODO: Is this plain?
-          [{ kind: :class_or_module, value: i }, { kind: :continuation, double: true }]
-        end.flatten
-
-        class_path.pop
-
-        if class_path.empty?
-          return {
-            kind: :const,
-            value: [
-              { kind: :class_or_module, value: value[:name] }
-            ].flatten
-          }
-        end
-
-        {
-          kind: :const,
-          value: [
-            class_path,
-            { kind: :continuation, double: true },
-            { kind: :class_or_module, value: value[:name] }
-          ].flatten
-        }
-      end
     end
   end
 end

data/lib/renderer/component/method_display.rb

@@ -3,7 +3,7 @@
 class Renderer
   class Component
     class MethodDisplay < Component
-      prop :visibility, :type, :name, :href, :args, :doc, :decoration, :short_type
+      prop :item, :omit_type, :parent
     end
   end
 end

data/lib/renderer/component/method_list.rb

@@ -3,7 +3,7 @@
 class Renderer
   class Component
     class MethodList < Component
-      prop :list
+      prop :list, :omit_type, :parent
     end
   end
 end

data/lib/renderer/component/reference.rb

@@ -3,21 +3,32 @@
 class Renderer
   class Component
     class Reference < Component
-      prop :ref, :unresolved, :path
+      prop :unresolved, :path, :ref_type, :object, :value
 
       def prepare
-        @unresolved = !ref[:ref_path]
-        return if @unresolved
+        case @object
+        when Docrb::Parser::Reference
+          @unresolved = !@object.fulfilled?
+          @path = [@object.path.last]
+          return if @unresolved
 
-        components = ref[:ref_path].dup
-        @path = if ref[:ref_type] == "method"
-                  method_name = components.pop
-                  parent_name = components.pop
-                  components + ["#{parent_name}.html#{method_name}"]
-                else
-                  last = components.pop
-                  (components + ["#{last}.html"]).compact
-                end
+          @object = @object.dereference!
+          prepare
+        when Docrb::Parser::Container
+          @path = [@object.name]
+          @ref_type = @object.kind
+          parent = @object.parent
+          until parent.nil?
+            @path << parent.name
+            parent = parent.parent
+          end
+          @path << ""
+          @path.reverse!
+        else
+          @ref_type = :pure
+          @value = @object[:value]
+          @object = @object[:object]
+        end
       end
     end
   end

data/lib/renderer/component/text_block.rb

@@ -3,13 +3,7 @@
 class Renderer
   class Component
     class TextBlock < Component
-      prop :list
-
-      def prepare
-        return unless !@list.nil? && !@list.is_a?(Array)
-
-        @list = [{ type: "html", contents: @list }]
-      end
+      prop :contents, :inline
     end
   end
 end

data/lib/renderer/component.rb

@@ -4,11 +4,11 @@ class Renderer
   class Component
     attr_accessor :id
 
-    def self.prop(*names)
-      attr_accessor(*names)
+    def self.prop(*)
+      attr_accessor(*)
 
       @props ||= []
-      @props.append(*names)
+      @props.append(*)
     end
 
     class << self
@@ -38,7 +38,7 @@ class Renderer
 
     def render(&)
       prepare
-      opts = props.map { [_1, send(_1)] }.to_h
+      opts = props.to_h { [_1, send(_1)] }
       opts[:id] = @id
       template.render(HELPERS, **opts, &)
     end

data/lib/renderer/core_extensions.rb

@@ -2,10 +2,21 @@
 
 class String
   def snakify
-    gsub(/::/, "/")
+    gsub("::", "/")
       .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
       .gsub(/([a-z\d])([A-Z])/, '\1_\2')
       .tr("-", "_")
       .downcase
   end
 end
+
+class Object
+  def object_id_hex = "0x#{object_id.to_s(16).rjust(16, "0")}"
+
+  def self.memo(name, &)
+    define_method(name) do
+      @__memoized_variables__ ||= {}
+      @__memoized_variables__[name] ||= instance_exec(&)
+    end
+  end
+end

data/lib/renderer/entities/attribute.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+class Renderer
+  module Entities
+    class Attribute
+      attr_accessor :name, :source, :definition, :overriding, :parent
+
+      def initialize(parent, name, model)
+        @name = name
+        @parent = parent
+        @source = model[:source] # TODO
+        @definition = AttributeDefinition.new(self, model[:definition])
+        @overriding = model[:overriding] # TODO
+      end
+    end
+  end
+end

data/lib/renderer/entities/attribute_definition.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+class Renderer
+  module Entities
+    class AttributeDefinition
+      attr_reader :defined_by, :doc, :name, :reader_visibility, :writer_visibility, :type, :parent
+
+      def initialize(parent, model)
+        @parent = parent
+        @defined_by = model[:defined_by]
+        @doc = model[:doc] # TODO
+        @name = model[:name]
+        @reader_visibility = model[:reader_visibility].to_sym
+        @writer_visibility = model[:writer_visibility].to_sym
+        @type = model[:type] # TODO
+      end
+
+      def accessor? = reader? && writer?
+      def reader? = reader_visibility == :public
+      def writer? = writer_visibility == :public
+    end
+  end
+end

data/lib/renderer/entities/base.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+class Renderer
+  module Entities
+    class Base
+      attr_accessor :name, :parent, :references
+
+      def initialize(parent, name)
+        @parent = parent
+        @name = name
+        @references = []
+      end
+
+      def type = raise NotImplementedError, "Classes inheriting Entities::Base must implement #type"
+
+      def module? = type == :module
+
+      def class? = type == :class
+
+      def def? = type == :def
+
+      def static? = type == :sdef
+
+      def root
+        obj = self
+        loop do
+          return obj if obj.parent.nil?
+
+          obj = obj.parent
+        end
+
+        raise "Orphaned object"
+      end
+
+      def inspect = "#<#{self.class.name}:#{object_id_hex} #{name}>"
+
+      def to_s = inspect
+
+      def root? = module? && parent.nil?
+
+      def register_reference(ref)
+        @references << ref
+      end
+
+      def full_path
+        parents = []
+        parent = self.parent
+        until parent.root?
+          parents << parent
+          parent = parent.parent
+        end
+
+        parents.reverse!
+        parents << self
+      end
+    end
+  end
+end

data/lib/renderer/entities/class.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+class Renderer
+  module Entities
+    class Class < Container
+      attr_accessor :attributes, :inherits
+
+      def initialize(parent, model)
+        super(parent, model)
+        @attributes = model.fetch(:attributes, {}).map { |k, v| Attribute.new(self, k.to_s, v) }
+        @inherits = init_reference(model[:inherits], :inherits)
+      end
+
+      def type = :class
+    end
+  end
+end