docrb-html 0.2.0

data/lib/renderer/helpers.rb

@@ -0,0 +1,82 @@
+class Renderer
+  class Helpers
+    def svg(name, **kwargs)
+      attrs = {}
+      cls = kwargs.delete(:class_name)
+      attrs["class"] = cls if cls
+      kwargs.each { |k, v| attrs[k.to_s] = v.to_s }
+
+      svg = File.read("assets/images/#{name}.svg")
+      return svg if attrs.empty?
+
+      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")
+    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(/"/, "\\\"")}\"" }
+
+      start_tag = "<div class=\"#{classes.join(" ")}\" #{args.join(" ")}>"
+      end_tag = "</div>"
+
+      fake_buffer = ""
+      old_buffer = block.binding.local_variable_get(:_erbout)
+      block.binding.local_variable_set(:_erbout, fake_buffer)
+      raw = block.call
+
+      captured = if fake_buffer.empty?
+                   raw
+                 else
+                   fake_buffer
+                 end
+    ensure
+      block.binding.local_variable_set(:_erbout, "#{start_tag}#{captured}#{end_tag}")
+    end
+
+    def capture(&block)
+      fake_buffer = ""
+      old_buffer = block.binding.local_variable_get(:_erbout)
+      block.binding.local_variable_set(:_erbout, fake_buffer)
+      raw = block.call
+
+      captured = if fake_buffer.empty?
+                   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 clean_file_path(source) = Renderer::Defs.singleton.clean_file_path(source)
+
+    def line_range(source)
+      from = source[:start_at]
+      to = source[:end_at]
+
+      if from == to
+        "line #{from}"
+      else
+        "lines #{from} to #{to}"
+      end
+    end
+  end
+
+  Component.constants
+           .reject { _1 == :HELPERS }
+           .each do |cls|
+    Helpers.define_method(cls.to_s.snakify) do |**kwargs|
+      Component.const_get(cls).new(**kwargs).render
+    end
+  end
+
+  Component.const_set(:HELPERS, Helpers.new)
+end

data/lib/renderer/metadata.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+class Renderer
+  class Metadata
+    def initialize(base)
+      @data = JSON.parse(File.read("#{base}/metadata.json"))
+    end
+
+    def format_authors
+      return nil if authors.nil? || authors.count.zero?
+      return authors.first if authors.length == 1
+
+      others = authors.count - 1
+      "#{authors.first}, and #{others} other#{others > 1 ? "s" : ""}"
+    end
+
+    def project_links
+      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
+      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/page.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+class Renderer
+  class Page
+    PAGE_BASE = Template.new("templates/base.erb")
+
+    def initialize(title: nil, level: 0, &body)
+      @title = "#{title} - Docrb"
+      @body = body || -> { "" }
+      @level = level
+    end
+
+    def render = PAGE_BASE.render(Object.new, title: @title, level: @level, body: @body.call)
+
+    def render_to(path) = File.write(path, render)
+  end
+end

data/lib/renderer/template.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+class Renderer
+  class Template
+    class Bind
+      def initialize(obj, **keys)
+        @obj = obj
+        @keys = keys
+      end
+
+      def method_missing(method_name, *args, **kwargs, &)
+        if @keys.include? method_name
+          @keys[method_name]
+        else
+          @obj.send(method_name, *args, **kwargs, &)
+        end
+      end
+
+      def respond_to_missing?(method_name, include_private = false)
+        @keys.key?(method_name.to_s) || @obj.respond_to_missing?(method_name, include_private)
+      end
+
+      def make_binding
+        binding
+      end
+    end
+
+    def initialize(path)
+      @template = ERB.new(File.read(path))
+      @template.filename = path
+    end
+
+    def render(b, *args, **kwargs)
+      bind = Bind.new(b, *args, **kwargs)
+      @template.result(bind.make_binding)
+    end
+  end
+end

data/lib/renderer/version.rb

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

data/lib/renderer.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+require "json"
+
+require "erb"
+require "sassc"
+require "nokogiri"
+
+require_relative "renderer/version"
+require_relative "renderer/core_extensions"
+require_relative "renderer/template"
+require_relative "renderer/component"
+require_relative "renderer/helpers"
+require_relative "renderer/page"
+require_relative "renderer/metadata"
+require_relative "renderer/defs"
+
+class Renderer
+  ASSETS_PATH = Pathname.new(__dir__).join("../assets")
+  STYLE_BASE = SassC::Engine.new(File.read(ASSETS_PATH.join("style.scss")),
+                                 style: :compressed,
+                                 load_paths: [ASSETS_PATH]).render
+
+  def now = Time.now.strftime("%A, %-d %b %Y %H:%M:%S %Z")
+
+  def initialize
+    @base = Pathname.new(ARGV.shift)
+    @output = Pathname.new(ARGV.shift)
+  end
+
+  def metadata = @metadata ||= Metadata.new(@base)
+  def defs = @defs ||= Defs.new(@base, metadata)
+  def footer = @footer ||= Component::Footer.new(version: "0.2.0", updated_at: now)
+
+  def render
+    project_header = Component::ProjectHeader.new(
+      name: metadata.name,
+      description: metadata.summary,
+      license: metadata.license,
+      owner: metadata.format_authors,
+      links: metadata.project_links
+    )
+
+    index = Page.new(title: "#{metadata.name} - Docrb") do
+      [
+        project_header,
+        Component::TabBar.new(
+          selected_index: 0,
+          items: [
+            { name: "Readme", href: "/" },
+            { name: "Components", href: "/components.html" }
+          ]
+        ),
+        Component::Markdown.new(source: File.read(@base.join("readme.html"))),
+        footer
+      ]
+    end
+
+    components = Page.new(title: "Components - #{metadata.name} - Docrb") do
+      [
+        project_header,
+        Component::TabBar.new(
+          selected_index: 1,
+          items: [
+            { name: "Readme", href: "/" },
+            { name: "Components", href: "/components.html" }
+          ]
+        ),
+        Component::ComponentList.new(list: defs.document_outline),
+        footer
+      ]
+    end
+
+    pages(defs.classes + defs.modules)
+
+    FileUtils.mkdir_p @output
+
+    index.render_to(@output.join("index.html"))
+    components.render_to(@output.join("components.html"))
+    File.write(@output.join("style.css"), STYLE_BASE)
+
+    copy_assets
+  end
+
+  def copy_assets
+    [
+      "js/filtering.js",
+      "favicon.ico"
+    ].each do |file|
+      File.write(@output.join(Pathname.new(file).basename),
+                 File.read(ASSETS_PATH.join(file)))
+    end
+  end
+
+  def pages(comps, parents = [])
+    comps.each do |comp|
+      page = Page.new(
+        title: "#{comp[:name]} - #{metadata.name} - Docrb",
+        level: parents.count
+      ) do
+        [
+          Component::ClassHeader.new(
+            type: comp[:type],
+            name: comp[:name],
+            definitions: defs.definitions_of(comp)
+          ),
+          Component::Breadcrumb.new(
+            project_name: metadata.name,
+            items: (parents + [comp]).map.with_index do |p, idx|
+              { name: p[:name], parents: parents[0...idx].map { _1[:name] } }
+            end
+          ),
+          Component::DocBox.new(
+            item: comp,
+            meta: metadata,
+            defs:
+          ),
+          footer
+        ]
+      end
+
+      parent_dir = @output.join(parents.map { _1[:name] }.join("/"))
+      FileUtils.mkdir_p(parent_dir)
+      page.render_to(parent_dir.join("#{comp[:name]}.html"))
+
+      pages(comp.fetch(:classes, []) + comp.fetch(:modules, []), parents + [comp])
+    end
+  end
+end

data/renderer.gemspec

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative "lib/renderer/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "docrb-html"
+  spec.version       = Renderer::VERSION
+  spec.authors       = ["Victor Gama"]
+  spec.email         = ["hey@vito.io"]
+
+  spec.summary       = "Docrb's HTML Generator"
+  spec.description   = spec.summary
+  spec.homepage      = "https://github.com/heyvito/docrb"
+  spec.license       = "MIT"
+  spec.required_ruby_version = ">= 3.2"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "#{spec.homepage}/tree/trunk/lib/docrb-html"
+  spec.metadata["changelog_uri"] = spec.homepage
+  spec.metadata["rubygems_mfa_required"] = "true"
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{\A(?:test|spec|features)/}) }
+  end
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "nokogiri", "~> 1.14"
+  spec.add_dependency "sassc", "~> 2.4"
+end

data/script/makecomponent

@@ -0,0 +1,23 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/renderer/core_extensions"
+name = ARGV.first.snakify
+real_name = ARGV.first
+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")
+File.write("lib/renderer/component/#{name}.rb", <<~RUBY)
+  class Renderer
+    class Component
+      class #{real_name} < Component
+      end
+    end
+  end
+RUBY
+
+File.write("templates/#{name}.erb", <<~ERB)
+  <% div("#{dashed_name}-base", id:) do %>
+  <% end %>
+ERB

data/script/reload.js

@@ -0,0 +1,14 @@
+(() => {
+    const go = () => {
+        fetch("http://localhost:8090", {
+             mode: 'no-cors',
+        })
+            .then(i => i.text())
+            .then(i => {
+                window.location.reload();
+                go();
+            })
+            .catch((e) => { console.error(e); go(); })
+    };
+    go();
+})();

data/script/serve

@@ -0,0 +1,2 @@
+#!/bin/bash
+docker run -it --rm -p 8000:80 --name web -v "$(cd "$(dirname "$1")"; pwd)/$(basename "$1")":/usr/share/nginx/html nginx

data/script/watch

@@ -0,0 +1,17 @@
+#!/bin/bash
+notifier &
+NOTIFIER_PID=$!
+
+trap 'kill $NOTIFIER_PID' INT TERM EXIT
+
+fswatch -0 lib assets templates | while read -d "" event; do
+  bundle exec exe/docrb-html work
+
+  for f in $(find output -name '*.html'); do
+    echo "<script>" >> "$f"
+    cat "script/reload.js" >> "$f"
+    echo "</script>" >> "$f"
+  done
+  kill -USR1 $NOTIFIER_PID
+  echo "Updated at $(date)"
+done

data/templates/base.erb

@@ -0,0 +1,25 @@
+<!DOCTYPE html>
+<html>
+<head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <title><%= title %></title>
+    <link rel="preconnect" href="https://fonts.googleapis.com" />
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossOrigin="true" />
+    <link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@300;400;500&family=Inter:wght@300;400;500&display=swap" rel="stylesheet" />
+    <% unless level.zero? %>
+    <base href="<%= ([".."] * level).join("/") %>" />
+    <% end %>
+    <link rel="stylesheet" type="text/css" href="style.css" />
+    <link rel="shortcut icon" href="favicon.ico" type="image/x-icon"/>
+    <link rel="icon" href="favicon.ico" type="image/x-icon"/>
+</head>
+<body>
+    <% if body.is_a? Array %>
+        <%= body.map(&:render).join("") %>
+    <% else %>
+        <%= body %>
+    <% end %>
+    <script type="text/javascript" src="filtering.js"></script>
+</body>
+</html>

data/templates/breadcrumb.erb

@@ -0,0 +1,28 @@
+<% div("breadcrumb-base", id:) do %>
+    <div class="link">
+        <a href="/">
+            <%= svg("home") %>
+            <span class="padded">
+                <%= project_name %>
+            </span>
+        </a>
+    </div>
+    <% items.each.with_index do |i, idx| %>
+        <%= svg("breadcrumb_separator") %>
+        <div class="link">
+            <% if i[:parents].empty? && idx == 0 %>
+                <a href="components.html">
+                    <span class="padded">
+                        <%= i[:name] %>
+                    </span>
+                </a>
+            <% else %>
+            <a href="<%= (i[:parents] + [idx == 0 ? nil : i[:name]]).flatten.compact.join("/") %>.html">
+                <span class="padded">
+                    <%= i[:name] %>
+                </span>
+            </a>
+            <% end %>
+        </div>
+    <% end %>
+<% end %>

data/templates/checkbox.erb

@@ -0,0 +1,8 @@
+<% div("checkbox-base") do %>
+    <input type="checkbox" id="<%= id %>" <%= checked && "checked" %>/>
+    <label for="<%= id %>">
+        <%= svg "checkbox-on", class_name: "checkbox-on" %>
+        <%= svg "checkbox-off", class_name: "checkbox-off" %>
+        <span class="label"><%= label %></span>
+    </label>
+<% end %>

data/templates/class_header.erb

@@ -0,0 +1,53 @@
+<% div("class-header-base", id:) do %>
+    <div class="class">
+        <h3 class="type"><%= type %></h3>
+        <h1 class="class-name"><%= name %></h1>
+        <% def_link = Proc.new do |item, extra = nil| %>
+        <span class="def-link">
+            <%= extra %>
+            <a href="<%= item[:href] %>"
+                class="dashed"><%= item[:name] %>
+            </a>
+        </span>
+        <% end %>
+        <% if definitions.length > 0 %>
+            <div class="defs">
+                Defined in
+                <% if def_collection.length == 1 %>
+                    <% def_link.call def_collection.first %>
+                <% else %>
+                    <% last_item = def_collection.pop %>
+                    <% def_collection.each do |item| %>
+                        <% def_link item %>
+                    <% end %>
+                    <% def_link.call last_item, " and " %>
+                <% end %>
+            </div>
+        <% end %>
+        <details class="chevron-container">
+            <summary>
+                <%= svg("chevron") %> <span class="collapsed">Show More</span> <span class="open">Show Less</span>
+            </summary>
+
+            <div class="toggles">
+                <div class="column">
+                    <%= checkbox(id: "filter-hide-internal", label: "Hide internal members", checked: false) %>
+                    <%= checkbox(id: "filter-hide-private", label: "Hide private members", checked: false) %>
+                </div>
+                <div class="column">
+                    <%= checkbox(id: "filter-hide-attrs", label: "Hide attributes", checked: false) %>
+                    <%= checkbox(id: "filter-hide-inherited", label: "Hide inherited members", checked: false) %>
+                </div>
+                <div class="column">
+                    <%= checkbox(id: "filter-show-extended", label: "Show extended members", checked: true) %>
+                    <%= checkbox(id: "filter-show-included", label: "Show included members", checked: true) %>
+                </div>
+            </div>
+        </details>
+    </div>
+    <div class="right">
+        <a href="https://github.com/heyvito/docrb" rel="noreferrer" target="_blank">
+            <%= svg('docrb-label') %>
+        </a>
+    </div>
+<% end %>

data/templates/class_mod_name.erb

@@ -0,0 +1,3 @@
+<% div("class-mod-name-base", id:) do %>
+    <a class="dashed" href="<%= href %>"><span class="type-name"><%= name %></span></a>
+<% end %>

data/templates/component_list.erb

@@ -0,0 +1,21 @@
+<% div("component-list-base", id:, class_name: class_name) do %>
+    <% list.each do |item| %>
+        <%
+            base_path = (parents + ["#{item[:name]}.html"]).join("/")
+            new_parents = parents + [item[:name]]
+        %>
+        <div class="level" style="padding-left: <%= item[:level] * 20 %>px">
+            <%= type_definition(type: item[:type], href: "#{base_path}", name: item[:name]) %>
+            <div class="level" style="padding-left: <%= (item[:level] + 1) * 20 %>px">
+                <% item[:attributes]&.each do |att| %>
+                    <%= method_display(type: att[:type], name: att[:name], visibility: att[:visibility], decoration: att[:decoration], href: "#{base_path}#attr-#{att[:name]}") %>
+                <% end %>
+                <% item[:defs]&.each do |met| %>
+                    <%= method_display(href: "#{base_path}##{met[:short_type]}-#{met[:name]}", **met) %>
+                <% end %>
+            </div>
+            <%= component_list(list: item[:modules], parents: new_parents, class_name: "no-margin") %>
+            <%= component_list(list: item[:classes], parents: new_parents, class_name: "no-margin") %>
+        </div>
+    <% end %>
+<% end %>

data/templates/doc_box.erb

@@ -0,0 +1,82 @@
+<% child_structure = Proc.new do |name, list| %>
+    <% if list && !list.length.zero? && list.is_a?(Array) %>
+        <div class="child-structure">
+            <h3 class="heading"><%= name %></h3>
+            <div class="link-column">
+                <% list.each do |item| %>
+                    <div>
+                        <% if item.is_a? String %>
+                            <%= reference(ref: { contents: item }) %>
+                        <% else %>
+                            <%= reference(ref: { ref_type: item.type, ref_path: item.path, contents: item.name }) %>
+                        <% end %>
+                    </div>
+                <% end %>
+            </div>
+        </div>
+    <% end %>
+<% end %>
+
+<% div("doc-box-base", id:) do %>
+    <div class="left">
+        <%= has_class_docs && documentation_block(doc: item[:doc]) %>
+        <% if has_class_details %>
+            <div class="section-container" id="class-details">
+                <div class="horizontal-container">
+                    <% child_structure.call("Inherits", [item.inherits].compact) %>
+                    <% child_structure.call("Extends", item.extends) %>
+                    <% child_structure.call("Includes", item.includes) %>
+                    <% child_structure.call("Child Modules", item.modules) %>
+                    <% child_structure.call("Child Classes", item.classes) %>
+                </div>
+            </div>
+        <% end %>
+        <% if has_attrs %>
+            <div class="section-container" id="attributes">
+                <h3 class="heading">Attributes</h3>
+                <% attrs.each do |att| %>
+                    <div class="attribute-container"
+                        data-origin="<%= att.dig(:origin) %>"
+                        data-type="<%= att[:type].downcase %>"
+                        id="<%= att[:type] %>-<%= att[:name] %>"
+                        >
+                        <% if att[:decoration] %>
+                            <%= svg(att[:decoration], class_name: "decoration", title: att[:decoration] == 'inherited' ? 'Inherited' : 'Override') %>
+                        <% end %>
+                        <span class="name"><%= att[:name] %></span>
+                        <span class="label"><%= att[:visibility] %></span>
+                        <% if att[:doc] %>
+                            <%= markdown(source: att[:doc]) %>
+                        <% else %>
+                            <div class="faded">
+                                (No documentation available)
+                            </div>
+                        <% end %>
+                    </div>
+                <% end %>
+            </div>
+        <% end %>
+        <% if has_class_methods %>
+            <div class="section-container" id="class-methods">
+                <h3 class="heading">Class Methods</h3>
+                <%= method_list(list: sdefs) %>
+            </div>
+        <% end %>
+        <% if has_instance_methods %>
+            <div class="section-container" id="instance-methods">
+                <h3 class="heading">Instance Methods</h3>
+                <%= method_list(list: defs) %>
+            </div>
+        <% end %>
+    </div>
+    <div class="right">
+        <% if page_components.any? { _1.last[:enabled] } %>
+            <h3>In this Page</h3>
+            <% page_components.map do |href, item| %>
+                <% if item[:enabled] %>
+                    <div><a href="#<%= href %>" class="dotted"><%= item[:name] %></a></div>
+                <% end %>
+            <% end %>
+        <% end %>
+    </div>
+<% end %>

data/templates/documentation_block.erb

@@ -0,0 +1,18 @@
+<% div("documentation-block-base", id:) do %>
+    <% if doc.nil? || doc.empty? %>
+        <div class="faded">(No documentation available)</div>
+    <% else %>
+        <% items = (doc[:contents].is_a?(Array) ? doc[:contents] : [doc[:contents]]).compact %>
+
+        <% items.map.each do |i| %>
+            <% if i[:type] == 'text_block' %>
+                <%= text_block list: i[:contents] %>
+            <% elsif i[:type] == 'code_example' %>
+                <%= markdown(source: i[:contents]) %>
+            <% elsif i[:type] == 'field_block' %>
+            <% else %>
+                <span class="text">!Unexpected item <%= i[:type] %></span>
+            <% end %>
+        <% end %>
+    <% end %>
+<% end %>

data/templates/footer.erb

@@ -0,0 +1,9 @@
+<% div("footer-base", id:) do %>
+    <div class="left">
+        Last updated <%= updated_at %>
+    </div>
+    <div class="right">
+        Generated by <a href="https://github.com/heyvito/docrb" class="dashed" rel="nofollow" target="_blank">Docrb</a>
+        version <%= version %>
+    </div>
+<% end %>