rtfdoc 0.1.3 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9526652b8cb796b8c425a270dbe24db31c72ac74dbc7b747dc467de1b45a9134
-  data.tar.gz: 8a155561cd6a0a949a872618f09ef694405e4d013fa1a6089467cc5d3f933d9f
+  metadata.gz: 347b6ddeab271092954187a8bd379383ce42ab72f8391800e580f75e9c62fcf9
+  data.tar.gz: 69b43ac24ce63fd20cdf5359b7e672dc449fa11b234c837c6945ad0334dac4c5
 SHA512:
-  metadata.gz: c67015811940e7cda515507725424bb9c7f9fc3b4c618cc86de0232d26762c29a522cdff08cf158f924fd4c7bd2a2693c64246184120b9b6eca5b670323df73f
-  data.tar.gz: 3eea133c9c2f2672ae869c0afa73bdaa6c871cc012bbb9576f4e554d35080c1069163abad49c572c568607bb8bafa2d0b7e5c51711dc70219b34a1bdf8cf0b46
+  metadata.gz: f80c5696294bbd63d9ae9d0deec899288d1124840c805a9ff0d8f1884db15b9885223b84642791dc9d37fe917cb86155bf380576a327ad17745ea414873069b9
+  data.tar.gz: abf40c249d97fc2bc9c1fda9e5e06a266acd4539cd011569233c8f91ea9f6a1ee41719c17f12f08331805c5e160e1e8a1ddd88114bd33755f82f15c4b72672ed

data/lib/rtfdoc.rb

@@ -7,6 +7,16 @@ require 'rtfdoc/version'
 
 module RTFDoc
   class AttributesComponent
+    # Needed because we can't call the same rendered within itself.
+    def self.private_renderer
+      @renderer ||= Redcarpet::Markdown.new(::RTFDoc::Renderer, {
+        underline:            true,
+        space_after_headers:  true,
+        fenced_code_blocks:   true,
+        no_intra_emphasis:    true
+      })
+    end
+
     def initialize(raw_attrs, title)
       @attributes = YAML.load(raw_attrs)
       @title      = title
@@ -16,6 +26,10 @@ module RTFDoc
     class_eval <<-RUBY
       define_method(:output) { #{template.src} }
     RUBY
+
+    def to_html(text)
+      self.class.private_renderer.render(text) if text
+    end
   end
 
   class Renderer < Redcarpet::Render::Base
@@ -39,6 +53,10 @@ module RTFDoc
       "<p>#{text}</p>"
     end
 
+    def link(link, title, content)
+      %(<a title="#{title}" href="#{link}">#{content}</a>)
+    end
+
     def header(text, level)
       if level == 4
         %(<div class="header-table">#{text}</div>)
@@ -113,17 +131,49 @@ module RTFDoc
   class Template
     attr_reader :app_name, :page_title
 
-    def initialize(sections, config)
-      @content      = sections.map(&:output).join
-      @menu_content = sections.map(&:menu_output).join
+    def initialize(nodes, config)
+      @content      = nodes.flat_map(&:output).join
+      # @menu_content = nodes.map(&:menu_output).join
       @app_name     = config['app_name']
       @page_title   = config['title']
+
+      generate_grouped_menu_content(nodes)
     end
 
     def output
       template = Erubi::Engine.new(File.read(File.expand_path('../src/index.html.erb', __dir__)))
       eval(template.src)
     end
+
+    private
+
+    # Transform a list of nodes into a list of groups. If all nodes already are groups, it will
+    # return the same list. Otherwise, it will build group from consecutives single resources.
+    def generate_grouped_menu_content(nodes)
+      i   = 0
+      res = []
+
+      while i < nodes.length
+        node = nodes[i]
+        if node.is_a?(Group)
+          res << node
+          i += 1
+        else
+          inner = []
+          j = i
+          while node && !node.is_a?(Group)
+            inner << node
+            j += 1
+            node = nodes[j]
+          end
+
+          res << Group.new(nil, inner)
+          i = j
+        end
+      end
+
+      @menu_content = res.map(&:menu_output).join
+    end
   end
 
   module RenderAsSection
@@ -247,16 +297,18 @@ module RTFDoc
     end
 
     def generate_example(sections)
-      endpoints   = sections.reject { |s| s.name == 'desc' || s.name == 'object' }
+      endpoints   = sections.reject { |s| s.is_a?(Scope) || s.name == 'desc' || s.name == 'object' }
       signatures  = endpoints.each_with_object("") do |e, res|
         res << %(<div class="resource-sig">#{e.signature}</div>)
       end
+      scopes = sections.select { |s| s.is_a?(Scope) }.map!(&:generate_example).join("\n")
 
       @example = <<-HTML
       <div class="section-response">
         <div class="response-topbar">ENDPOINTS</div>
         <div class="section-endpoints">#{signatures}</div>
       </div>
+      #{scopes}
       HTML
     end
 
@@ -273,6 +325,25 @@ module RTFDoc
       desc = nil
 
       sections = endpoints.each_with_object([]) do |endpoint, res|
+        if endpoint.is_a?(Hash)
+          n, values = endpoint.each_pair.first
+          next unless n.start_with?('scope|')
+          dir_name = n.slice(6..-1)
+
+          scope_name = values['title'] || dir_name
+          scoped_endpoints = values['endpoints']
+
+          subsections = scoped_endpoints.each_with_object([]) do |e, r|
+            filename = paths.dig(dir_name, e)
+            next unless filename
+            content  = File.read(filename)
+            r << Section.new(e, content, resource: name)
+          end
+
+          res << Scope.new(scope_name, subsections)
+          next res
+        end
+
         filename = paths[endpoint]
         next unless filename
 
@@ -300,7 +371,7 @@ module RTFDoc
       head, *tail = sections
       head.include_show_button = true
 
-      inner = sections.map(&:output).join("\n")
+      inner = sections.flat_map(&:output).join("\n")
       %(<section class="head-section">#{inner}</section>)
     end
 
@@ -308,11 +379,80 @@ module RTFDoc
       head, *tail = sections
       <<-HTML
         <li data-anchor="#{name}">
-          #{head.anchor(name.capitalize, class_list: 'expandable')}
+          #{head.anchor(human_name, class_list: 'expandable')}
           <ul>#{tail.map(&:menu_output).join}</ul>
         </li>
       HTML
     end
+
+    private
+
+    def human_name
+      name.tr('_', ' ').split.map!(&:capitalize).join(' ')
+    end
+  end
+
+  class Group
+    attr_reader :name, :resources
+
+    def initialize(name, resources, options = {})
+      @name       = name
+      @resources  = resources
+
+      sorted = true
+      sorted = options['sort'] if options.key?('sort')
+      @resources.sort! { |a, b| a.name <=> b.name } if sorted
+    end
+
+    def output
+      resources.map(&:output)
+    end
+
+    def menu_output
+      title = "<h5 class=\"nav-group-title\">#{name}</h5>" if name && name.length > 0
+
+      <<-HTML
+        <div class="sidebar-nav-group">
+          #{title}
+          <ul>#{resources.map(&:menu_output).join}</ul>
+        </div>
+      HTML
+    end
+  end
+
+  class Scope
+    attr_reader :name, :sections
+
+    def initialize(name, sections)
+      @name       = name
+      @sections   = sections
+    end
+
+    def output
+      sections.map(&:output)
+    end
+
+    def menu_output
+      <<-HTML
+        <li>
+          <div class="scope-title">#{name}</div>
+          <ul class="scoped">#{sections.map(&:menu_output).join}</ul>
+        </li>
+      HTML
+    end
+
+    def generate_example
+      signatures  = sections.each_with_object("") do |s, res|
+        res << %(<div class="resource-sig">#{s.signature}</div>)
+      end
+
+      <<-HTML
+      <div class="section-response">
+        <div class="response-topbar">#{name} ENDPOINTS</div>
+        <div class="section-endpoints">#{signatures}</div>
+      </div>
+      HTML
+    end
   end
 
   class Generator
@@ -325,18 +465,8 @@ module RTFDoc
     end
 
     def run
-      tree = build_content_tree
-
-      nodes = config['resources'].map do |rs|
-        if rs.is_a?(Hash)
-          name, endpoints = rs.each_pair.first
-          paths = tree[name]
-          Resource.build(name, paths, endpoints: endpoints)
-        else
-          paths = tree[rs]
-          paths.is_a?(Hash) ? Resource.build(rs, paths) : Section.new(rs, File.read(paths))
-        end
-      end
+      @tree = build_content_tree
+      nodes = build_nodes(config['resources'])
 
       out = File.new("#{Dir.tmpdir}/rtfdoc_output.html", 'w')
       out.write(Template.new(nodes, config).output)
@@ -345,6 +475,27 @@ module RTFDoc
 
     private
 
+    def build_nodes(ary, allow_groups: true)
+      ary.map do |rs|
+        if rs.is_a?(Hash)
+          name, values = rs.each_pair.first
+
+          if name.start_with?('group|')
+            raise 'Nested groups are not yet supported' if !allow_groups
+
+            group_name = values.key?('title') ? values['title'] : name.slice(6..-1)
+            Group.new(group_name, build_nodes(values['resources'], allow_groups: false), values)
+          else
+            paths = @tree[name]
+            Resource.build(name, paths, endpoints: values)
+          end
+        else
+          paths = @tree[rs]
+          paths.is_a?(Hash) ? Resource.build(rs, paths) : Section.new(rs, File.read(paths))
+        end
+      end
+    end
+
     def build_content_tree
       tree        = {}
       slicer      = (@content_dir.length + 1)..-1

data/lib/rtfdoc/version.rb

@@ -1,3 +1,3 @@
 module RTFDoc
-  VERSION = "0.1.3"
+  VERSION = "0.1.4"
 end

data/src/attributes.erb

@@ -1,5 +1,4 @@
 <div class="section-list">
-  <h5 class="section-list-title"><%= @title.capitalize %></h5>
   <ul>
     <% @attributes.each do |name, hash| %>
     <li class="list-item">
@@ -11,7 +10,7 @@
         <% end %>
       </div>
       <div class="list-item-description">
-        <p><%= hash['desc'] %></p>
+        <%= to_html(hash['desc']) %>
       </div>
       <% if hash['children']&.any? %>
         <div class="section-list section-list-child">
@@ -34,7 +33,7 @@
                   <div class="list-item-type"><%= child_hash['type'] %> </div>
                 </div>
                 <div class="list-item-description">
-                  <p><%= child_hash['desc'] %></p>
+                  <%= to_html(child_hash['desc']) %>
                 </div>
               </li>
             <% end %>

data/src/css/application.scss

@@ -17,6 +17,7 @@
   --content-width: calc(100vw - var(--sidebar-width));
   --section-padding: 5vw;
   --example-width: 40vw;
+  --max-example-width: 33vw;
   --sp20: 20px;
   --sp24: 24px;
   --monospace-font: "SFMono-Regular", "Consolas", "Menlo", monospace;
@@ -30,6 +31,7 @@
   --table-font-size: 14px;
   --table-line-height: 18px;
   --code-font-size: 14px;
+  --code-block-font-size: 13px;
 }
 
 * {
@@ -80,13 +82,15 @@ body[data-theme="dark"] {
   --nav-color: var(--sail-gray300);
   --nav-hover-color: var(--sail-gray50);
   --nav-header-color: var(--sail-gray50);
-  --brand-color: var(--sail-cyan500);
-  --switch-background-color: #212d63;
+  --brand-color: #4db7e8;
+  --switch-background-color: #3d4eac;
   --code-strings: #98c379;
   --code-numbers: #56b6c2;
   --code-booleans: #d19a66;
   --child-list-title-color: var(--sail-gray500);
   --child-list-title-hover-color: var(--sail-gray100);
+  --scoped-endpoints-title-color: var(--sail-gray50);
+  --link-color: #4db7e8;
 }
 
 body[data-theme="light"] {
@@ -121,6 +125,18 @@ body[data-theme="light"] {
   --code--booleans: #e36209;
   --child-list-title-color: #586069;
   --child-list-title-hover-color: #24292e;
+  --scoped-endpoints-title-color: var(--sail-cyan500);
+  --link-color: var(--sail-cyan500);
+}
+
+a, a:visited {
+  color: var(--link-color);
+  text-decoration: none;
+}
+
+a:hover {
+  color: var(--nav-hover-color);
+  text-decoration: none;
 }
 
 #sidebar {
@@ -151,26 +167,69 @@ body[data-theme="light"] {
 }
 
 .sidebar-nav {
-  margin-top: 16px; }
-  .sidebar-nav a {
-    text-decoration: none;
-    color: var(--nav-color);
-    transition: color .2s ease;
-    font-size: var(--nav-font-size);
-    font-weight: 500;
-    display: block;
-    padding: 5px 16px; }
-    .sidebar-nav a:hover {
-      color: var(--nav-hover-color); }
-  .sidebar-nav a.current span {
-    border-bottom: 2px solid var(--brand-color); }
-  .sidebar-nav li > ul {
-    display: none;
-    padding-left: 16px;
-    transition: all 2s ease; }
-  .sidebar-nav li.expanded > ul,
-  .sidebar-nav li.current > ul {
-    display: block; }
+  margin-top: 16px;
+  width: 100%;
+  max-height: 570px;
+  overflow-y: scroll;
+}
+
+.sidebar-nav-group {
+  padding-bottom: 12px;
+
+  h5 {
+    text-transform: uppercase;
+    margin: 0;
+    padding: 16px 16px 8px 16px;
+    color: var(--title-color);
+    font-size: 13px;
+    font-weight: 600;
+  }
+}
+
+.sidebar-nav a {
+  text-decoration: none;
+  color: var(--nav-color);
+  transition: color .2s ease;
+  font-size: var(--nav-font-size);
+  font-weight: 500;
+  display: block;
+  padding: 5px 16px;
+}
+
+.sidebar-nav a:hover {
+  color: var(--nav-hover-color);
+}
+
+.sidebar-nav a.current span {
+  border-bottom: 2px solid var(--brand-color);
+}
+
+.sidebar-nav li > ul {
+  display: none;
+  padding-left: 16px;
+  transition: all 2s ease;
+}
+
+.sidebar-nav li.expanded {
+  margin-bottom: 10px;
+}
+
+.sidebar-nav li.expanded > ul,
+.sidebar-nav li.current > ul {
+  display: block;
+}
+
+.sidebar-nav li > ul.scoped {
+  display: block;
+}
+
+.sidebar-nav .scope-title {
+  font-size: 13px;
+  color: var(--scoped-endpoints-title-color);
+  text-transform: uppercase;
+  font-weight: 400;
+  padding: 8px 0 3px 16px;
+}
 
 /*Simple css to style it like a toggle switch*/
 .theme-switch-wrapper {
@@ -302,18 +361,21 @@ section > section .section-divider {
 .section-body {
   flex-shrink: 0;
   width: calc(var(--example-width) - var(--section-padding));
-  margin-right: var(--section-padding); }
+  margin-right: var(--section-padding);
+
+  a { font-weight: 500; }
+}
 
 .section-example {
   position: sticky;
   align-self: flex-start;
   top: 0;
   flex-grow: 1;
-  max-width: 600px;
+  max-width: var(--max-example-width);
   padding-top: calc(40px + var(--sp20)); }
 
 p {
-  margin-top: var(--sp20);
+  margin-top: 16px;
   font-size: var(--main-font-size);
   line-height: var(--main-line-height);
   font-weight: 400;
@@ -345,7 +407,10 @@ ul {
   border-radius: 8px;
   box-shadow: 0 0 0 1px var(--response-shadow-color);
   max-height: 83vh;
-  overflow-y: auto;
+  overflow: hidden;
+  margin-bottom: 24px;
+
+  &:last-child { margin-bottom: 0 }
 
   .response-topbar {
     background: var(--block-header-background-color);
@@ -356,7 +421,7 @@ ul {
     border-radius: 8px 8px 0 0;
     text-transform: uppercase;
 
-    .endpoint-def .method { width: auto }
+    .endpoint-def { overflow-y: auto; }
   }
 
   p {
@@ -372,9 +437,13 @@ ul {
     font-size: var(--code-font-size);
     font-weight: 400;
     line-height: 18px;
+    max-height: 75vh;
+    overflow: auto;
   }
 }
 
+
+
 .endpoint-def {
   display: flex;
   flex-direction: row;
@@ -386,7 +455,6 @@ ul {
 
   .method {
     text-align: right;
-    width: 55px;
     margin-right: 7px;
     text-transform: uppercase;
   }
@@ -404,6 +472,7 @@ ul {
 
 .section-endpoints {
   padding: 12px 22px;
+  overflow-y: auto;
 
   a { text-decoration: none; }
   a:hover .method {
@@ -412,28 +481,27 @@ ul {
   a:hover .path {
     color: var(--endpoints-def-hover-color);
   }
-}
 
-h3 {
-  margin-top: 20px;
-  padding-top: 16px;
+  .resource-sig .method {
+    width: 55px;
+    min-width: 55px;
+  }
 }
 
-h3,
-.section-list .section-list-title {
+
+h3 {
   font-size: 16px;
   font-weight: 500;
-  padding-bottom: 12px;
+  padding: 24px 0 10px;
   border-bottom: 1px solid var(--divider-color);
   display: flex;
   align-items: baseline;
   color: var(--title-color);
   margin: 0;
-  margin-top: var(--sp20);
-  width: 100%; }
+  margin-top: 16px;
+  width: 100%;
+}
 
-.section-list {
-  margin-top: 32px; }
   .section-list .list-item {
     padding-top: 16px;
     padding-bottom: 15px;
@@ -544,12 +612,17 @@ p code {
   border: 1px solid var(--inline-code-border);
   padding: 2px 3px 0;
   margin: 0 1px;
-  font-size: var(--code-font-size);
+  font-size: .9em;
   font-family: var(--monospace-font);
   font-weight: 500;
   background: var(--inline-code-background); }
 
 /** Code highlighting **/
+pre code {
+  font-family: var(--monospace-font);
+  font-size: var(--code-block-font-size);
+}
+
 pre code,
 pre code .w {
   color: var(--code-color); }

data/src/index.html.erb

@@ -23,7 +23,7 @@
       </div>
     </div>
     <nav class="sidebar-nav" role="navigation">
-      <ul><%= @menu_content %></ul>
+      <%= @menu_content %>
     </nav>
   </div>
   <div id="content" class="content-area">

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rtfdoc
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.1.4
 platform: ruby
 authors:
 - ccocchi
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-08-17 00:00:00.000000000 Z
+date: 2021-01-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: erubi