yard-api 0.2.3 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: ab2e2a361011adda668edbcad1b71ba857fe61ab
-  data.tar.gz: c3ed5abc5b2de588e9722179e97acbc4c044986a
+  metadata.gz: 4174d158765fdfb8f72c2625f74d77e6bff1cf27
+  data.tar.gz: e50d4045d98142419848d2898b6a4fcf0989d9dc
 SHA512:
-  metadata.gz: d81dc23669668ed42dfc44e15c317b6199ab4be26cecfbc690abc0ab58b1209c0b15a984dd302ca7f0de8c00153f4e102ee0c060a354241724fc054c7b270957
-  data.tar.gz: 936a31ac15cecde12085d147565e92f51edef9251370ef33d9488ba9aa25d82473d64f48ca756a1235a3e6dbbd3d3f56abcd03ce27079379164e689eaafda338
+  metadata.gz: da95663074496a8b87e5ffaa29e922b95a6d2a75f04fd64165bd9f635ea79333777f196d8ecc8f0d6725b32603b27f0bf138a518e6bf6700afec4075e6fd99db
+  data.tar.gz: b6672a201e37c8f16829dd9f19a6836c956fb530799dbcab0cdd335a730008732a7f3d0bc8665c9bd2162f9ee991d8ee8c97946125dd977a962a1c8ddd8933c8

data/README.md

@@ -40,6 +40,10 @@ Read that file to view all the available options.
 
 ## Changelog
 
+**29/7/2015 [0.3.0]**
+
+- major rework of the linking logic, much improvements but some stuff is broken now
+
 **28/7/2015 [0.2.3]**
 
 - dropped the `@argument_scope` tag

data/config/yard_api.yml

@@ -61,7 +61,7 @@ strict: false
 #
 # Just specify the url to your repository and the branch the documentation has
 # been generated for and things "should work".
-# 
+#
 # Example: https://github.com/amireh/yard-api
 github_url:
 github_branch: master

data/lib/yard-api/code_objects/api_object.rb

@@ -0,0 +1,19 @@
+require 'yard/code_objects/class_object'
+
+module YARD::CodeObjects
+	class APIObject < Base
+		def path
+			super().gsub(/\s/, '')
+		end
+
+		def title
+			[ object.title, name ].join('::')
+		end
+	end
+
+	class ClassObject < NamespaceObject
+		def title
+			self[:api_id] || super
+		end
+	end
+end

data/lib/yard-api/options.rb

@@ -4,6 +4,8 @@ module YARD::APIPlugin
     default_attr :format, 'html'
     default_attr :no_save, false
 
+    default_attr :output, 'compiled/doc/api'
+
     default_attr :title, 'Rails API Project'
     default_attr :url_title, 'my_app'
     default_attr :url_prefix, '/api'
@@ -20,8 +22,8 @@ module YARD::APIPlugin
 
     default_attr :one_file, false
     default_attr :strict, false
-    default_attr :verbose, false
-    default_attr :debug, false
+    default_attr :verbose, ENV['VERBOSE'] || false
+    default_attr :debug, ENV['DEBUG'] || false
     default_attr :theme, 'default'
 
     default_attr :tabular_arguments, false
@@ -39,6 +41,9 @@ module YARD::APIPlugin
     default_attr :show_footer, true
     default_attr :readme_page_title, 'Home'
 
+    default_attr :resource_index, false
+    default_attr :centered, true
+
     attr_accessor :readme
   end
 end

data/lib/yard-api/registry.rb

@@ -0,0 +1,9 @@
+module YARD::APIPlugin
+	module Registry
+		def self.root
+			@root ||= begin
+			  YARD::Registry.register YARD::CodeObjects::NamespaceObject.new(:root, :API)
+			end
+		end
+	end
+end

data/lib/yard-api/serializer.rb

@@ -0,0 +1,61 @@
+module YARD::APIPlugin
+	class Serializer < ::YARD::Serializers::FileSystemSerializer
+		USNSEP = '__' # url-safe namespace separator
+		FSSEP = '/'
+
+	  def self.topicize(str)
+	    str.lines.first.gsub(/\W+/, '_').downcase
+	  end
+
+    def serialize(object, data)
+      path = File.join(basepath, serialized_path(object))
+
+      if path.include?(' ')
+      	debugger
+      end
+
+      log.debug "Serializing to #{path}"
+      File.open!(path, "wb") {|f| f.write data }
+    end
+
+    def serialized_path(object)
+      return object if object.is_a?(String)
+
+      fspath = nil
+
+      if object.is_a?(YARD::CodeObjects::ExtraFileObject)
+        fspath = 'file.' + object.name + (extension.empty? ? '' : ".#{extension}")
+      else
+        fspath = if object == YARD::Registry.root
+        	"top-level-namespace"
+        else
+        	self.class.topicize(get_api_id(object))
+        end
+
+        if object.is_a?(YARD::CodeObjects::MethodObject)
+        	fspath += '_' + object.scope.to_s[0,1]
+        end
+
+        unless extension.empty?
+      		fspath += ".#{extension}"
+      	end
+      end
+
+      if (fspath.include?(' '))
+      	debugger
+      end
+
+      fspath.gsub(/[^\w\.\-_\/]+/, '-')
+    end
+
+		def get_api_id(object)
+			if object[:api_id]
+				object.api_id
+			elsif tag = object.tag(:API)
+				tag.text.lines.first.strip
+			else
+				object.name.to_s
+			end
+		end
+	end
+end

data/lib/yard-api/templates/helpers/base_helper.rb

@@ -5,100 +5,100 @@ module YARD::Templates::Helpers::BaseHelper
     YARD::APIPlugin.options
   end
 
-  def linkify_with_api(*args)
-    # References to controller actions
-    #
-    # Syntax: api:ControllerName#method_name [TITLE OVERRIDE]
-    #
-    # @example Explicit reference with title defaulting to the action
-    #  # @see api:Assignments#create
-    #  # => <a href="assignments.html#method.assignments_api.create">create</a>
-    #
-    # @example Inline reference with an overriden title
-    #   # Here's a link to absolute {api:Assignments#destroy destruction}
-    #   # => <a href="assignments.html#method.assignments_api.destroy">destruction</a>
-    #
-    # @note Action links inside the All Resources section will be relative.
-    if args.first.is_a?(String) && args.first =~ %r{^api:([^#]+)#(.*)}
-      topic, controller = *lookup_topic($1.to_s)
-      if topic
-        html_file = "#{topicize topic.first}.html"
-        action = $2
-        link_url("#{html_file}#method.#{topicize(controller.name.to_s).sub("_controller", "")}.#{action}", args[1])
-      else
-        raise "couldn't find API link for #{args.first}"
-      end
-
-    # References to API objects defined by @object
-    #
-    # Syntax: api:ControllerName:Object+Name [TITLE OVERRIDE]
-    #
-    # @example Explicit resource reference with title defaulting to its name
-    #   # @see api:Assignments:Assignment
-    #   # => <a href="assignments.html#Assignment">Assignment</a>
-    #
-    # @example Explicit resource reference with an overriden title
-    #   # @return api:Assignments:AssignmentOverride An Assignment Override
-    #   # => <a href="assignments.html#Assignment">An Assignment Override</a>
-    elsif args.first.is_a?(String) && args.first =~ %r{^api:([^:]+):(.*)}
-      scope_name, resource_name = $1.downcase, $2.gsub('+', ' ')
-      link_url("#{scope_name}.html##{resource_name}", args[1] || resource_name)
-    elsif args.first.is_a?(String) && args.first == 'Appendix:' && args.size > 1
-      __errmsg = "unable to locate referenced appendix '#{args[1]}'"
-
-      unless appendix = lookup_appendix(args[1].to_s)
-        raise __errmsg
-      end
-
-      topic, controller = *lookup_topic(appendix.namespace.to_s)
-
-      if topic
-        html_file = "#{topicize topic.first}.html"
-        bookmark = "#{appendix.name.to_s.gsub(' ', '+')}-appendix"
-        ret = link_url("#{html_file}##{bookmark}", appendix.title)
-      else
-        raise __errmsg
-      end
-
-    # A non-API link, delegate to YARD's HTML linker
-    else
-      linkify_without_api(*args)
-    end
-  end
-
-  alias_method :linkify_without_api, :linkify
-  alias_method :linkify, :linkify_with_api
-
-  def lookup_topic(controller_name)
-    controller = nil
-    topic = options[:resources].find do |resource, controllers|
-      controllers.detect do |_controller|
-        if _controller.path.to_s == controller_name
-          controller = _controller
-        end
-      end
-    end
-
-    [ topic, controller ]
-  end
-
-  def lookup_appendix(title)
-    appendix = nil
-
-    YARD::APIPlugin.log("Looking up appendix: #{title}") if api_options.verbose
-
-    if object
-      # try in the object scope
-      appendix = YARD::Registry.at(".appendix.#{object.path}.#{title}")
-
-      # try in the object's namespace scope
-      if appendix.nil? && object.respond_to?(:namespace)
-        appendix = YARD::Registry.at(".appendix.#{object.namespace.path}.#{title}")
-      end
-    end
-
-    appendix
-  end
+  # def linkify_with_api(*args)
+  #   # References to controller actions
+  #   #
+  #   # Syntax: api:ControllerName#method_name [TITLE OVERRIDE]
+  #   #
+  #   # @example Explicit reference with title defaulting to the action
+  #   #  # @see api:Assignments#create
+  #   #  # => <a href="assignments.html#method.assignments_api.create">create</a>
+  #   #
+  #   # @example Inline reference with an overriden title
+  #   #   # Here's a link to absolute {api:Assignments#destroy destruction}
+  #   #   # => <a href="assignments.html#method.assignments_api.destroy">destruction</a>
+  #   #
+  #   # @note Action links inside the All Resources section will be relative.
+  #   if args.first.is_a?(String) && args.first =~ %r{^api:([^#]+)#(.*)}
+  #     topic, controller = *lookup_topic($1.to_s)
+  #     if topic
+  #       html_file = "#{topicize topic.first}.html"
+  #       action = $2
+  #       link_url("#{html_file}#method.#{topicize(controller.name.to_s).sub("_controller", "")}.#{action}", args[1])
+  #     else
+  #       raise "couldn't find API link for #{args.first}"
+  #     end
+
+  #   # References to API objects defined by @object
+  #   #
+  #   # Syntax: api:ControllerName:Object+Name [TITLE OVERRIDE]
+  #   #
+  #   # @example Explicit resource reference with title defaulting to its name
+  #   #   # @see api:Assignments:Assignment
+  #   #   # => <a href="assignments.html#Assignment">Assignment</a>
+  #   #
+  #   # @example Explicit resource reference with an overriden title
+  #   #   # @return api:Assignments:AssignmentOverride An Assignment Override
+  #   #   # => <a href="assignments.html#Assignment">An Assignment Override</a>
+  #   elsif args.first.is_a?(String) && args.first =~ %r{^api:([^:]+):(.*)}
+  #     scope_name, resource_name = $1.downcase, $2.gsub('+', ' ')
+  #     link_url("#{scope_name}.html##{resource_name}", args[1] || resource_name)
+  #   elsif args.first.is_a?(String) && args.first == 'Appendix:' && args.size > 1
+  #     __errmsg = "unable to locate referenced appendix '#{args[1]}'"
+
+  #     unless appendix = lookup_appendix(args[1].to_s)
+  #       raise __errmsg
+  #     end
+
+  #     topic, controller = *lookup_topic(appendix.namespace.to_s)
+
+  #     if topic
+  #       html_file = "#{topicize topic.first}.html"
+  #       bookmark = "#{appendix.name.to_s.gsub(' ', '+')}-appendix"
+  #       ret = link_url("#{html_file}##{bookmark}", appendix.title)
+  #     else
+  #       raise __errmsg
+  #     end
+
+  #   # A non-API link, delegate to YARD's HTML linker
+  #   else
+  #     linkify_without_api(*args)
+  #   end
+  # end
+
+  # alias_method :linkify_without_api, :linkify
+  # alias_method :linkify, :linkify_with_api
+
+  # def lookup_topic(controller_name)
+  #   controller = nil
+  #   topic = options[:resources].find do |resource, controllers|
+  #     controllers.detect do |_controller|
+  #       if _controller.path.to_s == controller_name
+  #         controller = _controller
+  #       end
+  #     end
+  #   end
+
+  #   [ topic, controller ]
+  # end
+
+  # def lookup_appendix(title)
+  #   appendix = nil
+
+  #   YARD::APIPlugin.log("Looking up appendix: #{title}") if api_options.verbose
+
+  #   if object
+  #     # try in the object scope
+  #     appendix = YARD::Registry.at(".appendix.#{object.path}.#{title}")
+
+  #     # try in the object's namespace scope
+  #     if appendix.nil? && object.respond_to?(:namespace)
+  #       appendix = YARD::Registry.at(".appendix.#{object.namespace.path}.#{title}")
+  #     end
+  #   end
+
+  #   appendix
+  # end
 
   def tag_partial(name, tag, locals={})
     options[:tag] = tag
@@ -121,4 +121,8 @@ module YARD::Templates::Helpers::BaseHelper
   def get_current_route
     get_current_routes.first
   end
+
+  def schema_is_model?(schema)
+    schema.has_key?('description') && schema.has_key?('properties')
+  end
 end

data/lib/yard-api/templates/helpers/html_helper.rb

@@ -2,7 +2,7 @@ require 'yard/templates/helpers/html_helper'
 
 module YARD::Templates::Helpers::HtmlHelper
   def topicize(str)
-    str.split("\n")[0].gsub(' ', '_').underscore
+    ::YARD::APIPlugin::Serializer.topicize(str)
   end
 
   def url_for_file(filename, anchor = nil)
@@ -11,6 +11,10 @@ module YARD::Templates::Helpers::HtmlHelper
     link
   end
 
+  # def url_for_api_object(name, object)
+  #   "#{object.parent.path}::#{name}"
+  # end
+
   def static_pages()
     @@static_pages ||= begin
       locate_static_pages(YARD::APIPlugin.options)
@@ -133,4 +137,22 @@ module YARD::Templates::Helpers::HtmlHelper
     html = resolve_links(html)
     html
   end
+
+  def htmlify_tag_type(tag)
+    co = if tag.type =~ /API::(?:(\S+)::)?(\S+)\b/
+      # discard [] at the end denoting array of objects
+      P(tag.type.gsub(/\[\]$/, ''))
+    end
+
+    if co && !co.is_a?(YARD::CodeObjects::Proxy)
+      begin
+        linkify(co, tag.type.split(YARD::CodeObjects::NSEP)[1..-1].join(YARD::CodeObjects::NSEP))
+      rescue Exception => e
+        YARD::APIPlugin.logger.warn e
+        ""
+      end
+    else
+      tag.type
+    end
+  end
 end

data/lib/yard-api/verifier.rb

@@ -24,6 +24,8 @@ module YARD
         case object.type
         when :root, :module, :constant
           false
+        when :api
+          true
         when :method, :class
           return false if object.tags('internal').any?
 

data/lib/yard-api/version.rb

@@ -1,5 +1,5 @@
 module YARD
   module APIPlugin
-    VERSION = "0.2.3"
+    VERSION = "0.3.0"
   end
 end

data/lib/yard-api.rb

@@ -37,6 +37,10 @@ module YARD
       log.enter_level(level) { log.puts(message) }
     end
 
+    def self.logger
+      YARD::Logger.instance
+    end
+
     def self.on_error(message)
       if self.options.strict
         raise message
@@ -48,8 +52,11 @@ module YARD
 
   require 'yard-api/version'
   require 'yard-api/options'
+  require 'yard-api/registry'
   require 'yard-api/tags'
   require 'yard-api/verifier'
+  require 'yard-api/serializer'
+  require 'yard-api/code_objects/api_object'
   require 'yard-api/templates/helpers/base_helper'
   require 'yard-api/templates/helpers/html_helper'
   require 'yard-api/templates/helpers/route_helper'
@@ -63,6 +70,16 @@ module YARD
     class YardocOptions < Templates::TemplateOptions
       default_attr :resources, []
       default_attr :json_objects, []
+      default_attr :controllers, []
+      default_attr :current_route, nil
+      default_attr :inline_file, nil
+      default_attr :all_resources, nil
+      default_attr :tag, nil
+      default_attr :locale, nil
+      default_attr :multi_dialect, false
+      default_attr :argument_tags, []
+      default_attr :output, nil
+      default_attr :json_objects_map, {}
     end
   end
 end

data/spec/fulldoc_spec.rb

@@ -0,0 +1,67 @@
+require 'spec_helper'
+
+module YARD
+  module Serializers
+    # A serializer that writes data to standard output.
+    class SpecSerializer < Base
+      # Creates a serializer to print text to stdout
+      #
+      # @param [Fixnum, nil] wrap if wrap is a number, wraps text to +wrap+
+      #   columns, otherwise no wrapping is done.
+      def initialize(buffer)
+        @buffer = buffer
+      end
+
+      # Overrides serialize behaviour to write data to standard output
+      def serialize(object, data)
+        @buffer << data
+      end
+    end
+  end
+end
+
+describe YARD::Templates::Engine.template(:api, :fulldoc) do
+  before do
+    Registry.clear
+    set_option("output", "./tmp/doc")
+  end
+
+  describe '@object' do
+    it 'should register it as a CodeObject inside the API namespace' do
+      populate <<-'eof'
+        # @API Quizzes
+        #
+        # @object Quiz
+        #   {
+        #     "id": "Quiz",
+        #     "description": "A quiz that can be taken by students.",
+        #     "properties": {
+        #       "id": {
+        #         "type": "String"
+        #       }
+        #     }
+        #   }
+        class QuizzesController < ApplicationController
+        end
+      eof
+
+      YARD::Templates::Engine.render({
+        objects: [ P('QuizzesController') ],
+        type: :fulldoc,
+        template: :api,
+        format: :html
+      })
+
+      expect(Registry.all.map(&:path).sort).to eq(%w[
+        API
+        API::Quiz
+        API::Quizzes
+        API::Quizzes::Quiz
+        QuizzesController
+      ])
+
+      expect(P('API::Quizzes::Quiz')).to be_truthy
+      expect(P('API::Quizzes::Quiz').parent).to eq P('API::Quizzes')
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -1,3 +1,5 @@
+require 'byebug'
+
 # This file was generated by the `rspec --init` command. Conventionally, all
 # specs live under a `spec` directory, which RSpec adds to the `$LOAD_PATH`.
 # The generated `.rspec` file contains `--require spec_helper` which will cause this
@@ -111,4 +113,15 @@ RSpec.configure do |config|
     @options.reset_defaults
     @overridden_options.clear
   end
+
+  Registry = YARD::Registry
+
+  def T(template)
+    YARD::Templates::Engine.template(:api)
+  end
+
+  def populate(str=nil)
+    Registry.clear
+    YARD.parse_string str if str
+  end
 end

data/templates/api/fulldoc/html/css/common.css

@@ -24,11 +24,7 @@ a.active {
 }
 
 code {
-  margin: 0 2px;
-  padding: 0px 5px;
-  border: 1px solid #ddd;
-  background-color: #f8f8f8;
-  border-radius: 3px;
+  background-color: #f5f5f5;
   font-family: Consolas, "Liberation Mono", Courier, monospace;
   font-weight: bold;
 }
@@ -47,13 +43,13 @@ h2 {
 
 .endpoint__beta-banner {
   border-left: 5px solid rgba(255,0,0,0.65);
-  background-color: #ffc;
+  background-color: #FFFBE6;
   padding: 0.6em;
   font-size: 85%;
 }
 
 .method-details__beta-flag {
-  color: #CC0000;
+  color: #800;
   background: #fca;
   padding: 0.5em 0.6em;
   font-size: 85%;
@@ -77,6 +73,8 @@ h2 {
   color: inherit;
   padding: 0.35em 0;
   text-decoration: none;
+  font-size: 85%;
+  line-height: 1.2;
 }
 
 #sidebar a:hover {
@@ -88,28 +86,31 @@ h2 {
 }
 
 .sidebar__heading {
-  color: #939da3;
+  color: #aaa;
   text-transform: uppercase;
   font-size: 1em;
   margin-bottom: 0.5em;
   padding-bottom: 0;
   margin-top: 1em;
+  font-weight: normal;
 }
 
 .endpoint__path {
-  font-size: 90%;
+  font-size: 85%;
   font-weight: normal;
   font-family: Monaco, Consolas, Courier, monospace;
-  padding: 1em;
-  margin-top: 1em;
-  background: #ffc;
+  padding: 0.5em;
+  margin: 1em 0;
+  background: #FFFBE6;
 }
 
-.method-details .verb {
+.method-details__verb {
   font-weight: bold;
+  color: #800;
 }
+
 .method-details .id-fragment {
-  color: #CC0000;
+  color: #800;
 }
 
 .method-details__defined-in {
@@ -135,7 +136,7 @@ h2 {
 /* highlight.js overrides */
 pre.code, div.syntaxhighlighter {
   font-family: Monaco, Consolas, Courier, monospace;
-  background-color: #ffd;
+  background-color: #FFFBE6;
   font-size: 85%;
   overflow: auto;
   padding: 0.5em 1em;
@@ -157,18 +158,29 @@ pre.code, div.syntaxhighlighter {
 
 td.code textarea { display: none; }
 
-table#quicklinks {
-  width: 100%;
+.topic__quicklinks {
+  padding: 0;
+  margin: 0;
 }
-table#quicklinks tr {
-  border: 1px solid black;
+
+.topic__quicklinks li {
+  list-style: none;
+  display: inline-block;
+  margin-right: 1em;
+  margin-bottom: 1em;
 }
-table#quicklinks td a {
-  padding: 6px;
+
+.topic__quicklinks li a {
+  display: block;
+  padding: 0.5em 1em;
+  background-color: #f5f5f5;
+  text-decoration: none;
+  border-radius: 3px;
+  font-size: 85%;
 }
-table#quicklinks th {
-  font-weight: bold;
-  padding: 12px;
+
+.topic__quicklinks li a:hover {
+  background-color: transparent;
 }
 
 a.method-details__name-link {
@@ -285,9 +297,6 @@ h4 {
 }
 
 code.argument-listing__argument-name {
-  border: none;
-  padding: 0;
-  margin: 0;
   overflow: auto;
 }
 
@@ -301,7 +310,7 @@ code.argument-listing__argument-name {
 
 .argument-listing__argument-required {
   font-style: normal;
-  color: #CC0000;
+  color: #800;
   font-weight: bold;
   opacity: 0.6;
 }
@@ -319,7 +328,7 @@ code.argument-listing__argument-name {
 
 .example-codeblocks__tabs {
   margin-bottom: -0.5em; /* negate the margin of the example block */
-  background: #ffc;
+  background: #FFF7CC;
   padding: 0.5em 1em;
   font-size: 85%;
 }
@@ -331,4 +340,44 @@ code.argument-listing__argument-name {
 
 .example-codeblocks__tabs a.active {
   font-weight: bold;
+}
+
+.type-mute {
+  color: #777;
+}
+
+.object-synopsis__header {
+  padding: 1em 0;
+  background: #FFFBE6;
+  position: relative; /* for the toggler btn */
+}
+
+.object-synopsis__header-text {
+  display: block;
+  width: 40%;
+  max-width: 260px;
+  text-align: right;
+}
+
+.object-synopsis__toggler {
+  appearance: none;
+  -webkit-appearance: none;
+  -moz-appearance: none;
+  border: none;
+  padding: 0;
+
+  background-color: transparent;
+  font-size: small;
+  color: #4183c4;
+  position: absolute;
+  top: 50%;
+  right: 1em;
+  margin-top: -0.5em;
+  cursor: pointer;
+  font-weight: bold;
+  line-height: 1;
+}
+
+.object-synopsis__toggler:hover {
+  text-decoration: underline;
 }

data/templates/api/fulldoc/html/js/app.js

@@ -1,6 +1,35 @@
+/* global $:true, hljs:true */
+
+function makeObjectSynopsisBlocksTogglable() {
+  var MARKER_CLASS = 'object-synopsis__hidden';
+
+  $('.object-synopsis__toggler').each(function() {
+    var $togglerButton = $(this);
+    var $objectSynopsis = $togglerButton.closest('.object-synopsis');
+    var $objectSynopsisContent = $objectSynopsis.find('.object-synopsis__content');
+
+    function render() {
+      if (!$togglerButton.hasClass(MARKER_CLASS)) {
+        $togglerButton.text('Hide');
+        $objectSynopsisContent.show();
+      }
+      else {
+        $togglerButton.text('Show');
+        $objectSynopsisContent.hide();
+      }
+    }
+
+    $togglerButton.on('click', function() {
+      $togglerButton.toggleClass(MARKER_CLASS);
+      render();
+    });
+
+    render();
+  });
+}
+
 $(function() {
   $('.method-details__name').each(function(i, el) {
-    var subtopic = $(el).data('subtopic');
     var $a = $(el).find('a');
     var anchorText = $.trim($a[0].innerHTML);
 
@@ -8,9 +37,9 @@ $(function() {
       return;
     }
 
-    var $row = $('#quicklinks');
+    var $row = $('#topicQuicklinks');
     var $link = $('<a/>', {
-      href: '#'+$(el).attr('name')
+      href: '#' + $(el).attr('name')
     }).html(anchorText);
 
     $('<li>').append($link).appendTo($row);
@@ -50,7 +79,9 @@ $(function() {
         $(this).addClass('active');
       });
     });
-    
+
     $(this).find('a:first').click();
   });
-});
+
+  makeObjectSynopsisBlocksTogglable();
+});

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

@@ -1,11 +1,21 @@
 require 'pathname'
+require 'json'
 
 include YARD::Templates::Helpers::ModuleHelper
 include YARD::Templates::Helpers::FilterHelper
 
 def init
+  YARD::APIPlugin.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].
-    group_by { |o| o.tags('API').first.text.split("\n").first }.
+    group_by { |o| o[:api_id] }.
     sort_by  { |o| o.first }
 
   build_json_objects_map
@@ -15,13 +25,51 @@ def init
     return serialize_onefile_index
   end
 
-  serialize_index if File.exists?(api_options['readme'])
+  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
+    end
+
     serialize_resource(resource, controllers)
   end
 end
@@ -34,12 +82,21 @@ def serialize(object)
 end
 
 def serialize_resource(resource, controllers)
+  YARD::APIPlugin.logger.info('=' * 80)
+  YARD::APIPlugin.logger.info ">>> #{resource} <<< (#{controllers})"
+  YARD::APIPlugin.logger.info('-' * 80)
+
   options[:object] = resource
   options[:controllers] = controllers
-  Templates::Engine.with_serializer("#{topicize resource}.html", options[:serializer]) do
-    T('layout').run(options)
+
+  controllers.each do |controller|
+    Templates::Engine.with_serializer(controller, options.serializer) do
+      T('layout').run(options)
+    end
   end
+
   options.delete(:controllers)
+  YARD::APIPlugin.logger.info('-' * 80)
 end
 
 def serialize_index
@@ -93,12 +150,55 @@ def build_json_objects_map
   options[:json_objects] = {}
   options[:resources].each do |r,cs|
     cs.each do |controller|
-      (controller.tags(:object) + controller.tags(:model)).each do |obj|
-        name, json = obj.text.split(%r{\n+}, 2).map(&:strip)
-        options[:json_objects_map][name] = topicize r
-        options[:json_objects][r] ||= []
-        options[:json_objects][r] << [name, json]
+      (controller.tags(:object) + controller.tags(:model)).each do |tag|
+        name, json_string = tag.text.split(%r{\n+}, 2).map(&:strip)
+
+        if json = parse_json(json_string)
+          options[:json_objects_map][name] = topicize r
+          options[:json_objects][r] ||= []
+          options[:json_objects][r] << [name, json]
+        end
       end
     end
   end
 end
+
+def parse_json(json_string)
+  JSON::parse(json_string || '').tap do |json|
+    validate_json_schema(json, ->(msg) {
+      raise <<-MSG
+        #{'=' * 32}
+        #{msg.strip}
+        #{'-' * 32}
+        Offending JSON belongs to: "#{name}" in "#{tag.object.path}".
+        #{'=' * 32}
+      MSG
+    })
+  end
+rescue JSON::ParserError => e
+  YARD::APIPlugin.on_error(
+    <<-MSG
+    #{'*' * 32}
+      A @#{tag.tag_name} docstring contains invalid JSON.
+      Offending JSON belongs to "#{name}" in "#{tag.object.path}".
+      ---
+      #{tag}
+      ---
+      #{e}
+    #{'*' * 32}
+    MSG
+  )
+
+  nil
+end
+
+def validate_json_schema(schema, on_error)
+  if schema_is_model?(schema)
+    if !schema['description'].is_a?(String)
+      on_error.call <<-MSG
+        Expected "description" to be a String, got #{schema['description'].class}.
+        Value: #{schema['description'].to_json}
+      MSG
+    end
+  end
+end

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

@@ -10,20 +10,21 @@
     body {
       margin: 0 auto;
       width: <%= content_width %>px;
+      padding-left: <%= sidebar_width %>px;
     }
- 
+
     #sidebar {
       margin-left: -<%= sidebar_width %>px;
       width: <%= sidebar_width %>px;
       left: auto;
     }
- 
+
     #content {
       padding-left: 3em;
     }
-  <% else %> 
+  <% else %>
     body {
-      padding-left: <%= sidebar_width + api_options.spacer %>px;
+      padding-left: <%= sidebar_width + (api_options.spacer || 0) %>px;
       padding-right: <%= api_options.spacer %>px;
     }
 

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

@@ -21,7 +21,7 @@
     <% end %>
 
     <% options[:resources].each do |resource, controllers| %>
-      <%= sidebar_link resource, "#{topicize(resource)}.html" %>
+      <%= sidebar_link resource, controllers.first %>
     <% end %>
   </nav>
 </div>

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

@@ -7,7 +7,10 @@
   %>
 
   <div class='endpoint__path'>
-    <span class="verb <%= route[:verb].downcase %>"><%= route[:verb] %></span>
+    <span class="method-details__verb <%= route[:verb].downcase %>">
+      <%= route[:verb] %>
+    </span>
+
     <%= formatted_route_path %>
   </div>
 

data/templates/api/tags/html/argument/_list.erb

@@ -1,11 +1,13 @@
 <ul class="argument-listing">
-  <% @argument_tags.each do |tag| %>
+  <% options[:argument_tags].each do |tag| %>
     <li class="argument-listing__argument">
       <div class="argument-listing__argument-details">
         <code class="argument-listing__argument-name"><%= h tag.name %></code>
-        <span class="argument-listing__argument-type"><%= tag.type %></span>
+        <span class="argument-listing__argument-type">
+          <%= htmlify_tag_type(tag) %>
+        </span>
 
-        <% if (tag.accepted_values || []).any? %>
+        <% if Array(tag.accepted_values).any? %>
           <span class="argument-listing__argument-values">
             <span>[ <%= tag.accepted_values.join(', ') %> ]</span>
           </span>
@@ -19,6 +21,8 @@
       <div class="argument-listing__argument-text">
         <% if !tag.text.empty? %>
           <%= html_markup_markdown(tag.text) %>
+        <% else %>
+          <em class="type-mute">No description provided.</em>
         <% end %>
       </div>
     </li>

data/templates/api/tags/html/argument/_table.erb

@@ -1,4 +1,5 @@
-<% has_accepted_values = @argument_tags.any? { |e| Array(e.accepted_values).any? } %>
+<% argument_tags = options[:argument_tags] %>
+<% has_accepted_values = argument_tags.any? { |e| Array(e.accepted_values).any? } %>
 
 <table>
   <thead>
@@ -12,7 +13,7 @@
   </thead>
 
   <tbody>
-    <% @argument_tags.each do |tag| %>
+    <% argument_tags.each do |tag| %>
       <tr>
         <td><code class="argument-name"><%= h tag.name %></code></td>
         <td><span class="argument-type"><%= tag.type %></span></td>

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

@@ -4,6 +4,7 @@
   <% else %>
     Returns <%= %w[a e i o u].include?(@resource_name[0]) ? 'an' : 'a' %>
   <% end %>
+
   <a href='<%= @resource_name %>.html#<%= @object_name %>'>
     <%= @is_list ? @object_name.pluralize : @object_name %>
   </a>

data/templates/api/tags/setup.rb

@@ -47,10 +47,10 @@ def emits
 end
 
 def argument
-  # generic_tag :argument, :no_types => false, :label => "Request Parameters"
-  @argument_tags = object.tags(:argument)
+  argument_tags = object.tags(:argument)
 
-  if @argument_tags.any?
+  if argument_tags.any?
+    options[:argument_tags] = argument_tags
     erb('argument')
   end
 end
@@ -66,6 +66,11 @@ def returns
     @object_name = response_info.text.strip
     @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/setup.rb

@@ -4,17 +4,18 @@ 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)
 end
 
 def method_details_list
-  @meths = options[:controllers].map { |c| c.meths(:inherited => false, :included => false) }.flatten
-  @meths = run_verifier(@meths)
   erb(:method_details_list)
 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] || []
   erb(:topic_doc)
@@ -28,6 +29,21 @@ def properties_of_model(json)
   end
 end
 
+def properties_of_model_as_tags(json)
+  props = json.has_key?('properties') ? json['properties'] : json
+  props.reduce([]) do |tags, (id, prop)|
+    is_required = prop.has_key?('required') ? prop['required'] : false
+    is_required_str = is_required ? 'Required' : 'Optional'
+
+    tag = YARD::APIPlugin::Tags::ArgumentTag.new(
+      nil,
+      "[#{is_required_str}, #{prop['type']}] #{id}\n #{prop['description']}"
+    )
+
+    tags << tag
+  end
+end
+
 def word_wrap(text, col_width=80)
   text.gsub!( /(\S{#{col_width}})(?=\S)/, '\1 ' )
   text.gsub!( /(.{1,#{col_width}})(?:\s+|$)/, "\\1\n" )

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

@@ -13,15 +13,50 @@
 <section>
   <h2>Interfaces</h2>
 
-  <ul id="quicklinks"></ul>
+  <% if @meths.empty? %>
+    <p>
+      <em class="type-mute">This API currently has no endpoints available.</em>
+    </p>
+  <% end %>
+
+  <ul id="topicQuicklinks" class="topic__quicklinks"></ul>
 </section>
 
-<% @json_objects.each do |name, json| %>
-  <% properties = render_properties(json) %>
-  <div class='object_definition'>
-    <h3>
-      <a name="<%= name %>"></a><%= name %> object synopsis:
-    </h3>
-    <pre class="example code"><%= html_syntax_highlight(properties ? properties : json, :plain) %></pre>
-  </div>
-<% end %>
+<% if @json_objects.any? %>
+  <section>
+    <h2>Object Synopses</h2>
+
+    <% @json_objects.each do |name, json| %>
+      <% if false %>
+        <% properties = render_properties(json) %>
+        <div class='object-synopsis'>
+          <h3>
+            <a name="<%= name %>"></a><%= name %> object synopsis:
+          </h3>
+          <pre class="example code"><%= html_syntax_highlight(properties ? properties : json, :plain) %></pre>
+        </div>
+      <% end %>
+
+      <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>
+<% end %>

data/yard-api.gemspec

@@ -19,4 +19,5 @@ Gem::Specification.new do |s|
   s.add_dependency 'yard-appendix'
   s.add_development_dependency 'rspec'
   s.add_development_dependency 'gem-release'
+  s.add_development_dependency 'byebug'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: yard-api
 version: !ruby/object:Gem::Version
-  version: 0.2.3
+  version: 0.3.0
 platform: ruby
 authors:
 - Ahmad Amireh
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-07-28 00:00:00.000000000 Z
+date: 2015-07-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: yard
@@ -66,6 +66,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: byebug
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: |2
       TBD
 email: ahmad@instructure.com
@@ -78,9 +92,12 @@ files:
 - README.md
 - config/yard_api.yml
 - lib/yard-api.rb
+- lib/yard-api/code_objects/api_object.rb
 - lib/yard-api/markup/redcarpet.rb
 - lib/yard-api/options.rb
 - lib/yard-api/railtie.rb
+- lib/yard-api/registry.rb
+- lib/yard-api/serializer.rb
 - lib/yard-api/tags.rb
 - lib/yard-api/tags/argument_tag.rb
 - lib/yard-api/templates/helpers/base_helper.rb
@@ -89,6 +106,7 @@ files:
 - lib/yard-api/verifier.rb
 - lib/yard-api/version.rb
 - lib/yard-api/yardoc_task.rb
+- spec/fulldoc_spec.rb
 - spec/spec_helper.rb
 - spec/tags/argument_spec.rb
 - tasks/yard_api.rake