yard-api 0.3.0 → 0.3.1

data/templates/api/fulldoc/html/setup.rb

@@ -5,86 +5,45 @@ include YARD::Templates::Helpers::ModuleHelper
 include YARD::Templates::Helpers::FilterHelper
 
 def init
-  YARD::APIPlugin.logger.info "YARD-API: starting."
+  logger.info "YARD-API: starting."
 
   options.serializer = YARD::APIPlugin::Serializer.new
   options.serializer.basepath = api_options.output
 
-  options.objects.each do |object|
-    object[:api_id] = object.tag('API').text.lines.first
-  end
-
-  options[:resources] = options[:objects].
+  options[:resources] = options.objects.
     group_by { |o| o[:api_id] }.
-    sort_by  { |o| o.first }
+    sort_by { |o| o.first }
 
-  build_json_objects_map
+  generate_endpoint_list(options[:resources])
+  generate_code_objects(options[:resources])
+  generate_json_object_map
   generate_assets
 
   if api_options.one_file
-    return serialize_onefile_index
-  end
-
-  serialize_index if File.exists?(api_options['readme'] || '')
-  serialize_static_pages
-  serialize_resource_index if api_options['resource_index']
-
-  options.delete(:objects)
-
-  options[:resources].each do |resource, controllers|
-    controllers.each do |controller|
-      if controller.is_a?(YARD::CodeObjects::NamespaceObject)
-        co = YARD::CodeObjects::ClassObject.new(
-          YARD::APIPlugin::Registry.root,
-          controller[:api_id]
-        )
-
-        YARD::Registry.register co
-
-        (controller.tags(:object) + controller.tags(:model)).each do |tag|
-          tag_co = YARD::CodeObjects::APIObject.new(co, tag.text.lines[0].strip)
-          tag_co.object = tag.object
-
-          # Make an alias on the global API namespace, for convenience.
-          # Now an object called "Bar" under the "Foo" controller can be
-          # referenced using [API::Bar] as well as [API::Foo::Bar] which will
-          # never face any conflicts.
-          shortcut_tag_co = YARD::CodeObjects::APIObject.new(YARD::APIPlugin::Registry.root, tag.text.lines[0].strip)
-          shortcut_tag_co.object = tag.object
-
-          # We need to override #namespace because #url_for() uses it to
-          # generate the url, which has to be done usign #object and not
-          # #namespace (which points to P("API") and we want
-          # P("API::#{tag.object.path}")).
-          shortcut_tag_co.namespace = tag.object
-
-          YARD::Registry.register(tag_co)
-          YARD::Registry.register(shortcut_tag_co)
-        end
-      end
-    end
-
-    # debugger
-
-    if controllers.length > 1
-      debugger
+    serialize_onefile_index
+  else
+    serialize_index if File.exists?(api_options['readme'] || '')
+    serialize_static_pages
+    serialize_resource_index if api_options['resource_index']
+
+    options[:resources].each do |resource, controllers|
+      serialize_resource(resource, controllers)
     end
-
-    serialize_resource(resource, controllers)
   end
 end
 
 def serialize(object)
   options[:object] = object
+
   Templates::Engine.with_serializer(object, options[:serializer]) do
     T('layout').run(options)
   end
+
+  options.delete(:object)
 end
 
 def serialize_resource(resource, controllers)
-  YARD::APIPlugin.logger.info('=' * 80)
-  YARD::APIPlugin.logger.info ">>> #{resource} <<< (#{controllers})"
-  YARD::APIPlugin.logger.info('-' * 80)
+  logger.debug "[=- #{resource} (#{controllers}) -=]"
 
   options[:object] = resource
   options[:controllers] = controllers
@@ -95,13 +54,17 @@ def serialize_resource(resource, controllers)
     end
   end
 
+  options.delete(:object)
   options.delete(:controllers)
-  YARD::APIPlugin.logger.info('-' * 80)
+
+  logger.info('-' * 80)
 end
 
 def serialize_index
   options[:file] = api_options['readme']
+
   serialize('index.html')
+
   options.delete(:file)
 end
 
@@ -117,23 +80,21 @@ end
 
 def serialize_resource_index
   options[:all_resources] = true
+  options[:object] = 'all_resources.html'
 
   Templates::Engine.with_serializer("all_resources.html", options[:serializer]) do
     T('layout').run(options)
   end
 
+  options.delete(:object)
   options.delete(:all_resources)
 end
 
-def asset(path, content)
-  options[:serializer].serialize(path, content) if options[:serializer]
-end
-
 def generate_assets
   layout = Object.new.extend(T('layout'))
 
-  [].concat(layout.stylesheets).concat(layout.javascripts).uniq.each do |file|
-    asset(file, file(file, true))
+  (layout.stylesheets + layout.javascripts).uniq.each do |file|
+    options.serializer.serialize(file, file(file, true))
   end
 end
 
@@ -145,7 +106,57 @@ def serialize_static_pages
   end
 end
 
-def build_json_objects_map
+def generate_code_objects(resources)
+  resources.each do |resource, controllers|
+    controllers.each do |controller|
+      if controller.is_a?(YARD::CodeObjects::NamespaceObject)
+        co = YARD::CodeObjects::ClassObject.new(
+          YARD::APIPlugin::Registry.root,
+          controller[:api_id]
+        )
+
+        YARD::Registry.register co
+
+        (controller.tags(:object) + controller.tags(:model)).each do |tag|
+          id = YARD::CodeObjects::APIObject.sanitize_id(tag.text.lines[0].strip)
+          tag_co = YARD::CodeObjects::APIObject.new(co, id)
+          tag_co.object = tag.object
+
+          # Make an alias on the global API namespace, for convenience.
+          # Now an object called "Bar" under the "Foo" controller can be
+          # referenced using [API::Bar] as well as [API::Foo::Bar] which will
+          # never face any conflicts.
+          shortcut_tag_co = YARD::CodeObjects::APIObject.new(YARD::APIPlugin::Registry.root, id)
+          shortcut_tag_co.object = tag.object
+
+          # We need to override #namespace because #url_for() uses it to
+          # generate the url, which has to be done usign #object and not
+          # #namespace (which points to P("API") and we want
+          # P("API::#{tag.object.path}")).
+          shortcut_tag_co.namespace = tag.object
+
+          YARD::Registry.register(tag_co)
+          YARD::Registry.register(shortcut_tag_co)
+        end
+      end
+    end
+  end
+end
+
+def generate_endpoint_list(resources)
+  options[:endpoints] ||= begin
+    resources.reduce({}) do |hsh, (resource, controllers)|
+      meths = controllers.map do |controller|
+        controller.meths(:inherited => false, :included => false)
+      end
+
+      hsh[resource] = run_verifier(meths.flatten)
+      hsh
+    end
+  end
+end
+
+def generate_json_object_map
   options[:json_objects_map] = {}
   options[:json_objects] = {}
   options[:resources].each do |r,cs|

data/templates/api/layout/html/layout.erb

@@ -21,6 +21,9 @@
           <% end %>
         <% end %>
 
+        <% @endpoints = options[:endpoints].values.flatten %>
+        <%= erb "../../topic/html/endpoints" %>
+
         <% options[:resources].each do |resource, controllers| %>
           <%= yieldall object: resource, controllers: controllers %>
         <% end %>

data/templates/api/layout/html/sidebar.erb

@@ -7,9 +7,18 @@
   <h2 class="sidebar__heading">API</h2>
 
   <nav id="static_pages">
-    <%= sidebar_link(api_options.readme_page_title, 'index.html') %>
+    <%=
+      sidebar_link(
+        'index.html',
+        api_options.readme_page_title,
+        options[:file] == api_options['readme']
+      )
+    %>
+
     <% static_pages.each do |page| %>
-      <%= sidebar_link(page[:title], page[:filename]) %>
+      <%=
+        sidebar_link(page[:filename], page[:title], object == page[:filename])
+      %>
     <% end %>
   </nav>
 
@@ -17,11 +26,19 @@
 
   <nav>
     <% if api_options['resource_index'] %>
-      <%= sidebar_link('All Resources', 'all_resources.html') %>
+      <%=
+        sidebar_link(
+          'all_resources.html',
+          'All Resources',
+          !!options[:all_resources]
+        )
+      %>
     <% end %>
 
     <% options[:resources].each do |resource, controllers| %>
-      <%= sidebar_link resource, controllers.first %>
+      <%=
+        sidebar_link(url_for(controllers[0]), resource.dup, resource == object)
+      %>
     <% end %>
   </nav>
 </div>

data/templates/api/method_details/html/header.erb

@@ -1,12 +1,8 @@
 <div class='method-details'>
-  <h2
-    class='method-details__name'
-    name='<%= @props[:method_link] %>'
-    data-subtopic='<%= @props[:subtopic] %>'
-  >
+  <h2 class='method-details__name'>
     <a
-      name='<%= @props[:method_link] %>'
-      href='#<%= @props[:method_link] %>'
+      name='<%= anchor_for(object) %>'
+      href='<%= url_for(object) %>'
       class='method-details__name-link'
     >
       <%= object.tag('API').text %>

data/templates/api/method_details/html/setup.rb

@@ -4,7 +4,6 @@ RouteHelper = YARD::Templates::Helpers::RouteHelper
 
 def init
   sections :header, [:method_signature, T('docstring')]
-  
 
   super
 end
@@ -23,19 +22,13 @@ def header
   end
 
   @props = {}
-  @props[:method_link] = [
-    'method',
-    route.requirements[:controller],
-    route.requirements[:action]
-  ].join('.')
-
-  @props[:subtopic] = (object.parent.tag('subtopic') || object.parent.tag('API')).text
+  @props[:method_link] = url_for(object)
 
   controller_path = "app/controllers/#{route.requirements[:controller]}_controller.rb"
 
   # TODO: can't we just test using object.file instead of relying on Rails ?
   controller_path = nil unless File.file?(Rails.root+controller_path)
-  
+
   if controller_path
     @props[:path] = controller_path
     @props[:controller] = route.requirements[:controller].camelize

data/templates/api/tags/html/_example_code_block.erb

@@ -2,20 +2,25 @@
 <% multi_dialect = options[:multi_dialect] %>
 <% title = tag.name %>
 <%
-	json_blob = begin
-		JSON.parse(tag.text).to_json
-	rescue JSON::ParserError => e
-		puts '*' * 80
-		puts "  Invalid JSON payload in endpoint: #{object.path.to_s}"
-		puts "  Please make sure it is valid JSON."
-		puts '*' * 80
-		
-		if api_options.strict then
-			raise e
-		else
-			return
-		end
-	end
+  json_blob = begin
+    text = tag.text.strip
+    if text[0] == '{' && text.last == '}'
+      JSON.parse(tag.text).to_json
+    else
+      nil
+    end
+  rescue JSON::ParserError => e
+    puts '*' * 80
+    puts "  Invalid JSON payload in endpoint: #{object.path.to_s}"
+    puts "  Please make sure it is valid JSON."
+    puts '*' * 80
+
+    if api_options.strict then
+      raise e
+    else
+      return
+    end
+  end
 %>
 
 <% if title && !title.empty? %>
@@ -23,29 +28,30 @@
 <% end %>
 
 <div class="example-codeblocks">
-	<% if multi_dialect %>
-		<div class="example-codeblocks__tabs">
-			<a class="example-codeblocks__tab">JSON</a>
-			<a class="example-codeblocks__tab">cURL</a>
-		</div>
-	<% end %>
+  <% if multi_dialect && json_blob %>
+    <div class="example-codeblocks__tabs">
+      <a class="example-codeblocks__tab">JSON</a>
+      <a class="example-codeblocks__tab">cURL</a>
+    </div>
+  <% end %>
+
+  <pre class="example-codeblocks__example example code js"><%= html_syntax_highlight(tag.text, :plain) %></pre>
 
-	<pre class="example-codeblocks__example example code js"><%= html_syntax_highlight(tag.text, :plain) %></pre>
-	<% if multi_dialect %>
-		<pre class="example-codeblocks__example example code shell">
+  <% if multi_dialect && json_blob %>
+    <pre class="example-codeblocks__example example code shell">
 curl \
   -X <%= YARD::Templates::Helpers::RouteHelper.get_route_verb(options[:current_route]) %> \
   -H "Authorization: Bearer $TOKEN" \
   -H 'Content-Type: application/json' \
   -H 'Accept: application/json' \
-  -d '<%= JSON.parse(tag.text).to_json %>' \
+  -d '<%= json_blob %>' \
   <%=
-  	[
-			"http://&lt;#{api_options.url_title}&gt;",
-			api_options.url_prefix,
-			YARD::Templates::Helpers::RouteHelper.get_route_path(options[:current_route])
-		].compact.reject(&:empty?).join('')
+    [
+      "http://&lt;#{api_options.url_title}&gt;",
+      api_options.url_prefix,
+      YARD::Templates::Helpers::RouteHelper.get_route_path(options[:current_route])
+    ].compact.reject(&:empty?).join('')
   %>
-		</pre>
-	<% end %>
+    </pre>
+  <% end %>
 </div>

data/templates/api/tags/html/returns.erb

@@ -1,11 +1,11 @@
+<% name = @resource_name %>
+
 <p class="returns-tag">
   <% if @is_list %>
     Returns a list of
   <% else %>
-    Returns <%= %w[a e i o u].include?(@resource_name[0]) ? 'an' : 'a' %>
+    Returns <%= %w[a e i o u].include?(name[0]) ? 'an' : 'a' %>
   <% end %>
 
-  <a href='<%= @resource_name %>.html#<%= @object_name %>'>
-    <%= @is_list ? @object_name.pluralize : @object_name %>
-  </a>
+  <%= link_url url_for(object), @is_list ? name.pluralize : name %>
 </p>

data/templates/api/tags/html/throws.erb

@@ -1,46 +1,50 @@
+<% has_code = false %>
+
 <h4>Possible Errors:</h4>
 <p>
-  Your request may be rejected with a <code>400 Bad Request</code> HTTP status
-  code and an error from the following set:
+  Your request may be rejected with an HTTP status code and an error message
+  from the following set:
 </p>
 
 <table class="endpoint-errors">
   <thead>
     <tr>
-      <!-- <th>Error</th> -->
-      <th>Code</th>
-      <th>Message</th>
+      <th>Response Code</th>
+      <th>Details</th>
     </tr>
   </thead>
 
   <tbody>
-    <% @error_tags.each do |tag| %>
+    <% object.tags(:throws).each do |tag| %>
       <%
-        tag.text ||= ''
-        error = {}
-        buf = tag.text.strip.sub(/^\[([^\]]+)\]/, '').strip
-        error[:status] = $1
-        buf = buf.sub(/"\[([^\]]+)\]([^"]+)"/, '').strip
-        error[:code] = $1.strip
-        error[:message] = $2
-        error[:cause] = buf.strip
+        error = JSON.parse(tag.text)
+        error[:reason] = error['reason'] || ''
+        error[:message] = error['message'] || ''
+        error[:status] = tag.type
       %>
+
       <tr>
-        <% if false %>
+        <td>
+          <%= error[:status] %>
+          <%= Rack::Utils::HTTP_STATUS_CODES[error[:status].to_i] %>
+        </td>
+
+        <% if has_code %>
           <td>
-            <%= error[:status] %>
-            <%= Rack::Utils::HTTP_STATUS_CODES[error[:status].to_i] %>
+            <code><%= error[:code] %></code>
           </td>
         <% end %>
+
         <td>
-          <code><%= error[:code] %></code>
-        </td>
-        <td>
-          <%= error[:message] %>
-          <% unless error[:cause].empty? %>
-            <hr />
-            <strong>Cause:</strong>
-            <%= error[:cause].sub(/^because /i, '').capitalize %>
+          <code>"<%= error[:message] %>"</code>
+
+          <% unless error[:reason].empty? %>
+            <p class="type-mute">
+              <em>
+                <!-- <p><strong>Reason:</strong></p> -->
+                <%= linkify error[:reason] %>
+              </em>
+            </p>
           <% end %>
         </td>
       </tr>

data/templates/api/tags/setup.rb

@@ -67,10 +67,6 @@ def returns
     @is_list = false
   end
 
-  # if @object_name =~ /\{(\S+)\}/
-  #   @object_name = $1
-  # end
-
   @resource_name = options[:json_objects_map][@object_name]
   return unless @resource_name
   erb(:returns)

data/templates/api/topic/html/endpoints.erb

@@ -0,0 +1,21 @@
+<section>
+  <% if options[:all_resources] %>
+    <h1>All Resources</h1>
+  <% end %>
+
+  <h2>Interfaces</h2>
+
+  <% if @endpoints.empty? %>
+    <p>
+      <em class="type-mute">This API currently has no endpoints available.</em>
+    </p>
+  <% else %>
+    <ul class="topic__quicklinks">
+      <% @endpoints.each do |endpoint| %>
+        <li>
+          <%= link_url '#' + anchor_for(endpoint), endpoint.tag(:API).text %>
+        </li>
+      <% end %>
+    </ul>
+  <% end %>
+</section>

data/templates/api/topic/html/header.erb

@@ -1,6 +1,10 @@
 <div class="service">
-  <% if @resource %>
-    <h1><%= @resource %> API</h1>
+  <% if object %>
+    <% if options[:all_resources] %>
+      <h2><%= object.to_s %> API</h2>
+    <% else %>
+      <h1><%= object.to_s %> API</h2>
+    <% end %>
   <% end %>
 
   <%= yieldall %>

data/templates/api/topic/html/method_details_list.erb

@@ -1,5 +1,5 @@
 <div>
-	<% @meths.each_with_index do |meth, i| %>
+	<% @endpoints.each_with_index do |meth, i| %>
 	  <%= yieldall :object => meth, :index => i %>
 	<% end %>
 </div>

data/templates/api/topic/html/object_synopses.erb

@@ -0,0 +1,26 @@
+<section>
+  <h2>Object Synopses</h2>
+
+  <% @json_objects.each do |name, json| %>
+    <div class="object-synopsis">
+      <h3 class="object-synopsis__header" id="<%= name %>-api">
+        <span class="object-synopsis__header-text"><%= name %></span>
+        <button class="object-synopsis__toggler"></button>
+      </h3>
+
+      <div class="object-synopsis__content">
+        <div class="object-synopsis__content-description">
+          <% if schema_is_model?(json) && !json['description'].empty? %>
+            <%= htmlify json['description'] %>
+          <% end %>
+        </div>
+
+        <%=
+          tag_partial("../../tags/html/argument/_list", nil, {
+            argument_tags: properties_of_model_as_tags(json)
+          })
+        %>
+      </div>
+    </div>
+  <% end %>
+</section>

data/templates/api/topic/html/setup.rb

@@ -2,10 +2,9 @@ require 'json'
 
 def init
   sections :header, [:topic_doc, :method_details_list, [T('method_details')]]
-  @resource = object
-  @beta = options[:controllers].any? { |c| c.tag('beta') }
-  @meths = options[:controllers].map { |c| c.meths(:inherited => false, :included => false) }.flatten
-  @meths = run_verifier(@meths)
+  @endpoints = options[:endpoints][object]
+
+  super
 end
 
 def method_details_list
@@ -14,10 +13,7 @@ end
 
 def topic_doc
   @docstring = options[:controllers].map { |c| c.docstring }.join("\n\n")
-  @object = @object.dup
-  @controller = options[:controllers].first
-  def @object.source_type; nil; end
-  @json_objects = options[:json_objects][@resource] || []
+  @json_objects = options[:json_objects][object] || []
   erb(:topic_doc)
 end