shaf 1.5.0 → 2.0.0

data/yard_templates/api_doc/profile_attribute/setup.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+include Shaf::Yard::NestedAttributes
+
+def init
+  super
+
+  @attribute = object
+  @nested_attributes = nested_attributes_for(object)
+
+  sections %i[attribute]
+end
+
+def value_types
+  Array(@attribute&.type).compact.map do |type|
+    {
+      type: type.to_s,
+      class_name: 'profile'
+    }
+  end
+end

data/yard_templates/api_doc/profile_relation/html/relation.erb

@@ -0,0 +1,37 @@
+<h4 class=description-list>
+    <strong> <%= object.name %></strong>
+</h4>
+<p><%= object.doc %></p>
+
+<% if href %>
+    <p>Reference: <a href="<%= href %>"><%= href %></a></p>
+<% end %>
+
+<% unless http_methods.empty? %>
+    <p>Supported HTTP Methods: <% http_methods.each do |method| %>
+        <span class="<%= css_classes_for(http_method: method) %>"><%= method %></span>
+        <%= %>
+    <% end %>
+    </p>
+<% end %>
+
+<% unless @nested_attributes.empty? %>
+    <div class="nested-attributes">
+        <h5>Nested attributes</h5>
+        <ul>
+        <% @nested_attributes.each do |key, attr| %>
+            <li>
+                <h6>
+                    <strong> <%= key %></strong>
+                    <span class="property-source profile"><%= attr.type %></span>
+                </h6>
+                <p><%= attr.doc %></p>
+            </li>
+        <% end %>
+        </ul>
+    </div>
+<% end %>
+
+<% if content_type %>
+    <p>Response type: <%= content_type %></p>
+<% end %>

data/yard_templates/api_doc/profile_relation/setup.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require 'forwardable'
+
+extend Forwardable
+include Shaf::Yard::NestedAttributes
+
+def_delegators :object, :name, :http_methods, :href, :content_type
+
+HTTP_METHODS = %w(head options get put patch post delete).freeze
+
+def init
+  super
+
+  @relation = object
+  @nested_attributes = nested_attributes_for(object)
+
+  sections %i[relation]
+end
+
+def value_types
+  Array(@attribute&.type).compact.map do |type|
+    {
+      type: type.to_s,
+      class_name: 'profile'
+    }
+  end
+end
+
+def css_classes_for(**options)
+  classes = []
+  classes.concat http_method_classes(options[:http_method]) if options.key? :http_method
+  classes.join(' ' )
+end
+
+def http_method_classes(method)
+  method = method.to_s.downcase
+  css_classes = ['http-method']
+  css_classes << method if HTTP_METHODS.include? method
+  css_classes
+end

data/yard_templates/api_doc/resource/html/attributes.erb

@@ -0,0 +1,10 @@
+<div class="resource-section attributes">
+  <h3>Attributes</h3>
+  <ul>
+    <% @attributes.each do |attr| %>
+      <li class="description-item">
+        <%= serialize_attribute(attr) %>
+      </li>
+    <% end %>
+  </ul>
+</div>

data/yard_templates/api_doc/resource/html/profile.erb

@@ -0,0 +1,14 @@
+<div class="resource-section media-type-profile">
+  <h3>Media type profile</h3>
+  <p>
+    <% profile_links.each do |profile_link| %>
+      <span class="property-source <%= profile_link[:css_classes] %>">
+        <% if profile_link[:href] %>
+        <a href="<%= profile_link[:href] %>"><%= profile_link[:name] %></a>
+        <% else %>
+        <span><%= profile_link[:name] %></span>
+        <% end %>
+      </span>
+    <% end %>
+  </p>
+</div>

data/yard_templates/api_doc/resource/html/relations.erb

@@ -0,0 +1,10 @@
+<div class="resource-section relations">
+  <h3>Link relations</h3>
+  <ul>
+    <% @relations.each do |rel| %>
+      <li class="description-item">
+        <%= serialize_relation(rel) %>
+      </li>
+    <% end %>
+  </ul>
+</div>

data/yard_templates/api_doc/resource/html/resource.erb

@@ -0,0 +1,5 @@
+<div class="resource">
+  <h2>The <span class="resource-title"><%= name %></span> resource</h2>
+  <p><%= description %>
+  <%= yieldall %>
+</div>

data/yard_templates/api_doc/resource/setup.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+def init
+  super
+
+  @attributes = object.attributes
+  @relations = object.links
+
+  sections :resource, %i[profile attributes relations]
+end
+
+def serialize_attribute(attr)
+  Templates::Engine.render(
+    template: :api_doc,
+    type: :resource_attribute,
+    object: attr,
+    format: options.format
+  )
+end
+
+def serialize_relation(rel)
+  Templates::Engine.render(
+    template: :api_doc,
+    type: :resource_relation,
+    object: rel,
+    format: options.format
+  )
+end
+
+def name
+  object.resource_name
+end
+
+def description
+  object.description
+end
+
+def profile_links
+  object.profile_objects.map do |profile_object|
+
+    if profile_object.profile
+      path = profile_object.path.sub(/Profiles::/, '')
+      href = "/api_doc/#{path}.html"
+      css_classes = 'profile'
+    else
+      href = nil
+      css_classes = 'unknown'
+    end
+
+    {
+      name: profile_object.profile_name,
+      href: href,
+      css_classes: css_classes
+    }
+  end
+end

data/yard_templates/api_doc/resource_attribute/html/attribute.erb

@@ -0,0 +1,23 @@
+<h4 class=description-list>
+    <strong> <%= object.name %></strong>
+    <% value_types.each do |type:, class_name:| %>
+        <span class="property-source <%= class_name %>"><%= type %></span>
+    <% end %>
+</h4>
+<p><%= object.documentation %></p>
+<% unless @nested_attributes.empty? %>
+    <div class="nested-attributes">
+        <h5>Nested attributes</h5>
+        <ul>
+        <% @nested_attributes.each do |key, attr| %>
+            <li>
+                <h6>
+                    <strong> <%= key %></strong>
+                    <span class="property-source profile"><%= attr.type %></span>
+                </h6>
+                <p><%= attr.doc %></p>
+            </li>
+        <% end %>
+        </ul>
+    </div>
+<% end %>

data/yard_templates/api_doc/resource_attribute/setup.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+include Shaf::Yard::NestedAttributes
+
+def init
+  super
+
+  @attribute = object
+  @nested_attributes = nested_attributes_for(object.descriptor)
+
+  sections %i[attribute] end
+
+def value_types
+  object.value_types.map do |type|
+    {
+      type: type,
+      class_name: 'profile'
+    }
+  end
+end

data/yard_templates/api_doc/resource_relation/html/relation.erb

@@ -0,0 +1,47 @@
+<h4 class=description-list>
+    <strong> <%= object.name %></strong>
+</h4>
+<p><%= object.documentation %></p>
+
+<p>Source:
+    <% if source.href %>
+        <span class="property-source <%= source.type %>">
+            <a href="<%= source.href %>"><%= source.name %></a>
+        </span>
+    <% else %>
+        <span class="property-source <%= source.type %>"><%= source.name %></span>
+    <% end %>
+</p>
+
+<% if href %>
+    <p>Reference: <a href="<%= href %>"><%= href %></a></p>
+<% end %>
+
+<% unless http_methods.empty? %>
+    <p>Supported HTTP Methods: <% http_methods.each do |method| %>
+        <span class="<%= css_classes_for(http_method: method) %>"><%= method %></span>
+        <%= %>
+    <% end %>
+    </p>
+<% end %>
+
+<% unless @nested_attributes.empty? %>
+    <div class="nested-attributes">
+        <h5>Nested attributes</h5>
+        <ul>
+        <% @nested_attributes.each do |key, attr| %>
+            <li>
+                <h6>
+                    <strong> <%= key %></strong>
+                    <span class="property-source profile"><%= attr.type %></span>
+                </h6>
+                <p><%= attr.doc %></p>
+            </li>
+        <% end %>
+        </ul>
+    </div>
+<% end %>
+
+<% if content_type %>
+    <p>Response type: <%= content_type %></p>
+<% end %>

data/yard_templates/api_doc/resource_relation/setup.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require 'forwardable'
+
+extend Forwardable
+include Shaf::Yard::NestedAttributes
+
+def_delegators :object, :name, :http_methods, :href, :content_type
+
+HTTP_METHODS = %w(head options get put patch post delete).freeze
+IANA_HREF = 'https://www.iana.org/assignments/link-relations/link-relations.xhtml'
+
+class Source
+  attr_reader :name, :href, :type
+
+  def initialize(name:, href:, type:)
+    @name, @href, @type = name, href, type
+  end
+end
+
+def init
+  super
+
+  @nested_attributes = nested_attributes_for(object.descriptor)
+
+  sections %i[relation]
+end
+
+def source
+  return @source if defined? @source
+
+  # We currently only support one profile per resource.
+  # But this might change in the future.
+  profile_objects = [object.profile_object].compact
+  profile_objects.each do |profile_object|
+    next unless profile_object.profile.find_relation(name)
+
+    path = profile_object.path.sub(/Profiles::/, '')
+
+    @source = Source.new(
+      name: profile_object.name,
+      href: "/api_doc/#{path}.html",
+      type: :profile
+    )
+    break
+  end
+
+  @source ||= iana_source if object.iana_doc
+  @source ||= unknown_source
+  @source
+end
+
+def iana_source
+  Source.new(
+    name: 'IANA',
+    href: IANA_HREF,
+    type: :iana
+  )
+end
+
+def unknown_source
+  Source.new(
+    name: 'Unknown',
+    href: nil,
+    type: :unknown
+  )
+end
+
+def css_classes_for(**options)
+  classes = []
+  classes.concat http_method_classes(options[:http_method]) if options.key? :http_method
+  classes.join(' ' )
+end
+
+def http_method_classes(method)
+  method = method.to_s.downcase
+  css_classes = ['http-method']
+  css_classes << method if HTTP_METHODS.include? method
+  css_classes
+end

data/yard_templates/api_doc/setup.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require 'shaf/profiles'
+
+def init
+  super
+
+  init_options
+end
+
+def init_options
+  options.resources = YARD::Registry.all(:resource)
+  options.profiles = YARD::Registry.all(:profile)
+end
+
+def serializer(base_path: nil)
+  YARD::Serializers::FileSystemSerializer.new.tap do |serializer|
+    base_path ||= self.base_path
+    serializer.basepath = base_path
+  end
+end
+
+def base_path
+  "#{public_path}/api_doc"
+end
+
+def public_path
+  path = String(Shaf::Settings.public_folder)
+  return 'public' if path.empty?
+  path
+end

data/yard_templates/api_doc/sidebar/html/profile_list.erb

@@ -0,0 +1,8 @@
+<div id="profile-list" class="list sidebar-content <%= 'active' if profile? %>">
+  <ul>
+    <% @profiles.each do |name:, path:| %>
+      <li class="sidebar-link <%= 'active' if profile_active?(name) %>">
+        <a href=<%= path %> class="<%= 'active' if profile_active?(name) %>"><%= name%></a>
+      </li>
+    <% end %>
+</div>

data/yard_templates/api_doc/sidebar/html/search.erb

@@ -0,0 +1,7 @@
+<%# TODO: This partial is urrently not used!! %>
+<div id="search" class="sidebar-search">
+  <form>
+    <label for="search">Search</label>
+    <input id="search-input" type="text">
+  </form>
+</div>

data/yard_templates/api_doc/sidebar/html/serializer_list.erb

@@ -0,0 +1,8 @@
+<div id="serializer-list" class="list sidebar-content <%= 'active' if resource? || index? %>">
+  <ul>
+    <% @resources.each do |name:, path:| %>
+      <li class="sidebar-link <%= 'active' if resource_active?(name) %>">
+        <a href=<%= path %> class="<%= 'active' if resource_active?(name) %>"><%= name%></a>
+      </li>
+    <% end %>
+</div>