yard-api 0.3.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 4174d158765fdfb8f72c2625f74d77e6bff1cf27
-  data.tar.gz: e50d4045d98142419848d2898b6a4fcf0989d9dc
+  metadata.gz: 57a2787c3ce762f1d68efe7aba2d1407443a7fb0
+  data.tar.gz: 9abaebf7932f1dffbaa3f84fe8c43cce1cf7c266
 SHA512:
-  metadata.gz: da95663074496a8b87e5ffaa29e922b95a6d2a75f04fd64165bd9f635ea79333777f196d8ecc8f0d6725b32603b27f0bf138a518e6bf6700afec4075e6fd99db
-  data.tar.gz: b6672a201e37c8f16829dd9f19a6836c956fb530799dbcab0cdd335a730008732a7f3d0bc8665c9bd2162f9ee991d8ee8c97946125dd977a962a1c8ddd8933c8
+  metadata.gz: b41c9b4518e06b4a772b846004c9f8b849526091604e6d3051d855d14caaf6ebc5ec34b557e83c4b1edd3e9b60242c670d4e345204a18a42b80a397a0930c17a
+  data.tar.gz: ec814f8e0e70e29a2ec528f08a1f434def22383fc41f159e25cd31eda57cd67496b1b0f8e4565c424c59125a9a75b2d6296ae33235b19a2f0ca827e027b5c98c

data/README.md

@@ -40,6 +40,11 @@ Read that file to view all the available options.
 
 ## Changelog
 
+**30/7/2015 [0.3.1]**
+
+- Fixed a bug that was listing all the endpoints of a certain controller even if they do not have a route defined. Now, YARD-API will warn about endpoints that have an `@API` tag but could not be routed.
+- Greatly improved the performance of generating the Quicklinks table.
+
 **29/7/2015 [0.3.0]**
 
 - major rework of the linking logic, much improvements but some stuff is broken now

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

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

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

@@ -0,0 +1,19 @@
+require 'yard/code_objects/class_object'
+
+module YARD::CodeObjects
+  class ClassObject < NamespaceObject
+    attr_reader :api_id
+
+    def api_id
+      @api_id ||= begin
+        if tag = tag('API')
+          tag.text.lines.first
+        end
+      end
+    end
+
+    def title
+      api_id
+    end
+  end
+end

data/lib/yard-api/serializer.rb

@@ -1,20 +1,14 @@
 module YARD::APIPlugin
-	class Serializer < ::YARD::Serializers::FileSystemSerializer
-		USNSEP = '__' # url-safe namespace separator
-		FSSEP = '/'
+  class Serializer < ::YARD::Serializers::FileSystemSerializer
+    USNSEP = '__' # url-safe namespace separator
+    FSSEP = '/'
 
-	  def self.topicize(str)
-	    str.lines.first.gsub(/\W+/, '_').downcase
-	  end
+    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
 
@@ -27,35 +21,31 @@ module YARD::APIPlugin
         fspath = 'file.' + object.name + (extension.empty? ? '' : ".#{extension}")
       else
         fspath = if object == YARD::Registry.root
-        	"top-level-namespace"
+          "top-level-namespace"
         else
-        	self.class.topicize(get_api_id(object))
+          self.class.topicize(get_api_id(object))
         end
 
         if object.is_a?(YARD::CodeObjects::MethodObject)
-        	fspath += '_' + object.scope.to_s[0,1]
+          fspath += '_' + object.scope.to_s[0,1]
         end
 
         unless extension.empty?
-      		fspath += ".#{extension}"
-      	end
-      end
-
-      if (fspath.include?(' '))
-      	debugger
+          fspath += ".#{extension}"
+        end
       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
+    def get_api_id(object)
+      if object[:api_id]
+        object.api_id
+      elsif tag = object.tag(:API)
+        tag.text.lines.first.strip
+      else
+        object.to_s
+      end
+    end
+  end
 end

data/lib/yard-api/tags.rb

@@ -6,13 +6,12 @@ YARD::Tags::Library.define_tag("API response field", :request_field)
 YARD::Tags::Library.define_tag("API response field", :response_field)
 YARD::Tags::Library.define_tag("API example request", :example_request, :with_title_and_text)
 YARD::Tags::Library.define_tag("API example response", :example_response, :with_title_and_text)
-YARD::Tags::Library.define_tag("API subtopic", :subtopic)
 YARD::Tags::Library.define_tag("API Object Definition", :object)
 YARD::Tags::Library.define_tag("API Return Type", :returns)
 YARD::Tags::Library.define_tag("API resource is beta", :beta)
 YARD::Tags::Library.define_tag("API resource is internal", :internal)
 YARD::Tags::Library.define_tag("API empty response", :no_content)
-YARD::Tags::Library.define_tag("API error", :throws)
+YARD::Tags::Library.define_tag("API error", :throws, :with_types)
 YARD::Tags::Library.define_tag("API warning", :warning)
 YARD::Tags::Library.define_tag("API note", :note)
 YARD::Tags::Library.define_tag("API message", :emits)

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

@@ -5,100 +5,23 @@ 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
+  def lookup_appendix(title)
+    appendix = nil
 
-  #   # 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]}'"
+    logger.debug("Looking up appendix: #{title}")
 
-  #     unless appendix = lookup_appendix(args[1].to_s)
-  #       raise __errmsg
-  #     end
+    if object
+      # try in the object scope
+      appendix = YARD::Registry.at(".appendix.#{object.path}.#{title}")
 
-  #     topic, controller = *lookup_topic(appendix.namespace.to_s)
+      # 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
 
-  #     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
+    appendix
+  end
 
   def tag_partial(name, tag, locals={})
     options[:tag] = tag
@@ -110,12 +33,7 @@ module YARD::Templates::Helpers::BaseHelper
   end
 
   def get_current_routes
-    controller_name = object.parent.path.underscore
-    controller_name.sub!("_controller", '') unless controller_name.include?('/')
-
-    action = object.path.sub(/^.*#/, '').sub(/_with_.*$/, '')
-
-    YARD::Templates::Helpers::RouteHelper.api_methods_for_controller_and_action(controller_name, action)
+    YARD::Templates::Helpers::RouteHelper.routes_for_yard_object(object)
   end
 
   def get_current_route
@@ -125,4 +43,8 @@ module YARD::Templates::Helpers::BaseHelper
   def schema_is_model?(schema)
     schema.has_key?('description') && schema.has_key?('properties')
   end
+
+  def logger
+    YARD::APIPlugin.logger
+  end
 end

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

@@ -5,16 +5,12 @@ module YARD::Templates::Helpers::HtmlHelper
     ::YARD::APIPlugin::Serializer.topicize(str)
   end
 
-  def url_for_file(filename, anchor = nil)
-    link = filename.filename
+  def url_for_file(file, anchor = nil)
+    link = file.filename
     link += (anchor ? '#' + urlencode(anchor) : '')
     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)
@@ -61,9 +57,7 @@ module YARD::Templates::Helpers::HtmlHelper
           .capitalize
       )
 
-      if options.verbose
-        puts "Serializing static page #{page} (#{title})"
-      end
+      logger.debug "Serializing static page #{page} (#{title})"
 
       {
         src: page,
@@ -76,10 +70,11 @@ module YARD::Templates::Helpers::HtmlHelper
 
   # override yard-appendix link_appendix
   def link_appendix(ref)
-    puts "Linking appendix: #{ref}" if api_options.verbose
+    logger.debug "Linking appendix: #{ref}"
 
     unless appendix = lookup_appendix(ref.to_s)
-      raise "Unable to locate referenced appendix '#{ref}'"
+      YARD::APIPlugin.on_error "Unable to locate referenced appendix '#{ref}'"
+      return ref
     end
 
     html_file = if options[:all_resources] && api_options.one_file
@@ -87,39 +82,23 @@ module YARD::Templates::Helpers::HtmlHelper
     elsif options[:all_resources]
       'all_resources.html'
     else
-      topic, controller = *lookup_topic(appendix.namespace.to_s)
-
-      unless topic
-        raise "Unable to locate topic for appendix: #{ref}"
-      end
-
-      "#{topicize(topic.first)}.html"
+      url_for(appendix.namespace)
     end
 
     bookmark = "#{appendix.name.to_s.gsub(' ', '+')}-appendix"
     link_url("#{html_file}##{bookmark}", appendix.title).tap do |link|
-      puts "\tAppendix link: #{link}" if api_options.verbose
+      logger.debug "\tAppendix link: #{link}"
     end
   end
 
-  # TODO: this has to work with the All Resources page.
-  def sidebar_link(title, href, options={})
-    options[:class_name] ||= begin
-      if object.is_a?(String) && "#{url_for(topicize(object))}.html" == href
-        options[:class_name] = 'active'
-      end
-    end
-
-    options[:class_name] ||= (object == href ? 'active' : nil)
-
-    <<-HTML
-      <a href="#{url_for(href)}" class="#{options[:class_name]}">#{title}</a>
-    HTML
+  def sidebar_link(href, title, is_active)
+    link_url(href, title, { class: is_active ? 'active' : '' })
   end
 
   # Turns text into HTML using +markup+ style formatting.
   #
   # @override Syntax highlighting is not performed on the HTML block.
+  #
   # @param [String] text the text to format
   # @param [Symbol] markup examples are +:markdown+, +:textile+, +:rdoc+.
   #   To add a custom markup type, see {MarkupHelper}
@@ -155,4 +134,23 @@ module YARD::Templates::Helpers::HtmlHelper
       tag.type
     end
   end
+
+  # @override
+  #
+  # Because we want the endpoints' URLs (an anchor part) to show up as
+  # "-endpoint" as opposed to "-instance_method"
+  def anchor_for_with_api(object)
+    case object
+    when YARD::CodeObjects::MethodObject
+      "#{object.name}-endpoint"
+    else
+      anchor_for_without_api(object)
+    end
+  end
+  alias_method :anchor_for_without_api, :anchor_for
+  alias_method :anchor_for, :anchor_for_with_api
+
+  def logger
+    YARD::APIPlugin.logger
+  end
 end

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

@@ -1,27 +1,38 @@
 module YARD::Templates::Helpers
   module RouteHelper
-    def self.routes_for(prefix)
-      Rails.application.routes.set
-    end
+    class << self
+      def routes_for(prefix)
+        Rails.application.routes.set
+      end
 
-    def self.matches_controller_and_action?(route, controller, action)
-      route.requirements[:controller] == controller &&
-      route.requirements[:action] == action
-    end
+      def routes_for_yard_object(api_object)
+        controller_name = api_object.parent.path.underscore
+        controller_name.sub!('_controller', '') unless controller_name.include?('/')
 
-    def self.api_methods_for_controller_and_action(controller, action)
-      @routes ||= self.routes_for('/')
-      controller_path = [ YARD::APIPlugin.options.route_namespace, controller ].join('/')
-      controller_path.gsub!(/^\/|_controller$/, '')
-      @routes.find_all { |r| matches_controller_and_action?(r, controller_path, action) }
-    end
+        action = api_object.path.sub(/^.*#/, '').sub(/_with_.*$/, '')
 
-    def self.get_route_path(route)
-      route.path.spec.to_s.gsub("(.:format)", "")
-    end
+        api_methods_for_controller_and_action(controller_name, action)
+      end
+
+      def matches_controller_and_action?(route, controller, action)
+        route.requirements[:controller] == controller &&
+        route.requirements[:action] == action
+      end
+
+      def api_methods_for_controller_and_action(controller, action)
+        @routes ||= routes_for('/')
+        controller_path = [ YARD::APIPlugin.options.route_namespace, controller ].join('/')
+        controller_path.gsub!(/^\/|_controller$/, '')
+        @routes.find_all { |r| matches_controller_and_action?(r, controller_path, action) }
+      end
+
+      def get_route_path(route)
+        route.path.spec.to_s.gsub("(.:format)", "")
+      end
 
-    def self.get_route_verb(route)
-      route.verb.source =~ /\^?(\w*)\$/ ? $1.upcase : route.verb.source
+      def get_route_verb(route)
+        route.verb.source =~ /\^?(\w*)\$/ ? $1.upcase : route.verb.source
+      end
     end
   end
 end

data/lib/yard-api/verifier.rb

@@ -3,6 +3,7 @@ module YARD
     class Verifier < ::YARD::Verifier
       def initialize(verbose=false)
         @verbose = verbose
+        @routes = {}
         super()
       end
 
@@ -10,10 +11,10 @@ module YARD
         relevant = list.select { |o| relevant_object?(o) }
 
         if @verbose && relevant.any?
-          log "#{relevant.length}/#{list.length} objects are relevant:"
+          logger.debug "#{relevant.length}/#{list.length} objects are relevant:"
 
           relevant.each do |object|
-            log "\t- #{object.path}"
+            logger.debug "\t- #{object.path}"
           end
         end
 
@@ -26,21 +27,31 @@ module YARD
           false
         when :api
           true
-        when :method, :class
-          return false if object.tags('internal').any?
+        when :method
+          return false if object.has_tag?(:internal) || !object.has_tag?(:API)
+          routes = @routes[object.object_id]
+          routes ||= begin
+            @routes[object.object_id] = YARD::Templates::Helpers::RouteHelper.routes_for_yard_object(object)
+          end
 
-          object.tags('API').any?.tap do |is_api|
-            if @verbose && !is_api
-              log "Resource #{object} will be ignored as it contains no @API tag."
-            end
+          if routes.empty?
+            logger.warn (
+              "API Endpoint #{object.path}# has no routes defined " +
+              "ib routes.rb and will be ignored."
+            )
           end
+
+          routes.any?
+        when :class
+          return false if object.has_tag?(:internal) || !object.has_tag?(:API)
+          true
         else
           object.parent.nil? && relevant_object?(object.parent)
         end
       end
 
-      def log(*args)
-        ::YARD::APIPlugin.log(*args)
+      def logger
+        ::YARD::APIPlugin.logger
       end
     end
   end

data/lib/yard-api/version.rb

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

data/lib/yard-api.rb

@@ -57,6 +57,7 @@ module YARD
   require 'yard-api/verifier'
   require 'yard-api/serializer'
   require 'yard-api/code_objects/api_object'
+  require 'yard-api/code_objects/class_object'
   require 'yard-api/templates/helpers/base_helper'
   require 'yard-api/templates/helpers/html_helper'
   require 'yard-api/templates/helpers/route_helper'
@@ -80,6 +81,8 @@ module YARD
       default_attr :argument_tags, []
       default_attr :output, nil
       default_attr :json_objects_map, {}
+      default_attr :endpoints, nil
+      default_attr :resource_name, nil
     end
   end
 end

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

@@ -294,6 +294,7 @@ h4 {
 .argument-listing__argument-values,
 .argument-listing__argument-required {
   display: block;
+  word-wrap: break-word;
 }
 
 code.argument-listing__argument-name {
@@ -380,4 +381,4 @@ code.argument-listing__argument-name {
 
 .object-synopsis__toggler:hover {
   text-decoration: underline;
-}
+}

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

@@ -29,22 +29,6 @@ function makeObjectSynopsisBlocksTogglable() {
 }
 
 $(function() {
-  $('.method-details__name').each(function(i, el) {
-    var $a = $(el).find('a');
-    var anchorText = $.trim($a[0].innerHTML);
-
-    if (anchorText === '') {
-      return;
-    }
-
-    var $row = $('#topicQuicklinks');
-    var $link = $('<a/>', {
-      href: '#' + $(el).attr('name')
-    }).html(anchorText);
-
-    $('<li>').append($link).appendTo($row);
-  });
-
   $('#content pre').each(function(i, block) {
     var code;
     var $block = $(block);