yard-api 0.1.10 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 2f894b7c9e0efdee454a068de0105e061b713784
-  data.tar.gz: a5eb169d8372bcea684866395a2a4ecddda65385
+  metadata.gz: 867bf4c5f7af54dcfe89527e5aa33b3028573ae0
+  data.tar.gz: 55bee11b6e7fbf8a94f43e17750f908ca0ea286b
 SHA512:
-  metadata.gz: 297b3d21420a0a60052d77f4d2748ed252e32298e78b3e87d2b7f13f6229efe389483b52bc4f309399b87eb5b816befe0f91c7be4fa479aa81f383890b453479
-  data.tar.gz: fea346e1cee3d55253920f2fba306f797a5a86c41e74418e42958ace2d96dd2269499808df1f345080716f002ee4afd8816c93686cec1b9235e1d1459e9d7cc0
+  metadata.gz: 855c761049489fe7c9f22fc786093580ee7de47ecd93a1f4945e70e35e64be2d1a1d4c780e0997101ea81fdfb4e48acb7b90a41f9b46acc1daa2ebcb172104fc
+  data.tar.gz: 3a0efa005c097a27e400ad6b00189aa8a3f57469929a9f37199766f00cb928f0a22004dca2f6daabf8dd7f66af284957e0be0a377f36aae533fa54d0ea089f0d

data/config/yard_api.yml

@@ -1,7 +1,6 @@
 ---
 # config/yard_api.yml
 output: public/doc/api
-source: doc/api
 readme: doc/api/README.md
 
 # Title of the project. This will be displayed in the browser title bar as well
@@ -32,6 +31,8 @@ markup_provider:
 files:
   - app/controllers/**/*.rb
 
+route_namespace:
+
 # YARD assets that you want to reference from your docs. The key is the
 # reference key you use in the docs, while the value is the path to where
 # the assets are located relative to the doc source.
@@ -40,8 +41,8 @@ files:
 #
 # See "source" and "output".
 assets:
-  images: images
-  examples: examples
+  # images: images
+  # examples: examples
 
 # Debug option. YARD and YARD-API verbosity option.
 verbose: true
@@ -57,7 +58,9 @@ strict: false
 #
 # Just specify the url to your repository and the branch the documentation has
 # been generated for and things "should work".
-github_url: https://github.com/amireh/yard-api
+# 
+# Example: https://github.com/amireh/yard-api
+github_url:
 github_branch: master
 
 # Set to true if you want @argument tags to show up in a table instead of a list.

data/lib/yard-api/options.rb

@@ -1,10 +1,12 @@
 module YARD::APIPlugin
   # See config/yard_api.yml for documentation for the options.
   class Options < YARD::Options
+    default_attr :format, 'html'
+    default_attr :no_save, false
+
     default_attr :title, 'Rails API Project'
     default_attr :window_title, 'Rails API Project Documentation'
     default_attr :version, ''
-    default_attr :source, 'doc/api'
     default_attr :static, []
     default_attr :files, []
     default_attr :route_namespace, ''
@@ -15,6 +17,7 @@ module YARD::APIPlugin
     default_attr :footer_note, ''
 
     default_attr :one_file, false
+    default_attr :strict, false
     default_attr :verbose, false
     default_attr :debug, false
     default_attr :theme, 'default'

data/lib/yard-api/tags/argument_tag.rb

@@ -7,6 +7,7 @@ module YARD::APIPlugin::Tags
     RE_NAME = /^([\S]+)/
     RE_ARRAY_LITERAL = /\[[^\]]+\]/
     RE_ARRAY_TYPE = /^#{RE_ARRAY_LITERAL}$/
+    RE_REQUIRED_OPTIONAL = /required|optional/i
     RE_ACCEPTED_VALUES_PREFIXES = /
       accepted\svalues |
       accepts |
@@ -38,18 +39,19 @@ module YARD::APIPlugin::Tags
       YARD::Tags::Library.instance.tag_create(:attr, buf).tap do |tag|
         super(:argument, tag.text, tag.types, name || tag.name)
 
+        @types ||= []
+        @text ||= ''
+
         @is_required = parse_is_required(@types)
         @accepted_values = parse_accepted_values(@types, @text)
       end
     end
 
     def unscoped_name
-      if scope_tag = @object.tag(:argument_scope)
-        if @name =~ /^#{scope_tag.text}\[([^\]]+)\]$/
-          $1
-        else
-          @name
-        end
+      scope_tag = @object.tag(:argument_scope)
+
+      if scope_tag && @name =~ /^#{scope_tag.text.gsub(/\[\]/, '')}\[([^\]]+)\]$/
+        $1
       else
         @name
       end
@@ -57,36 +59,51 @@ module YARD::APIPlugin::Tags
 
     private
 
-    def parse_is_required(types)
+    def parse_is_required(types=[])
       strict = !!YARD::APIPlugin.options.strict_arguments
-      specifier = types.detect { |typestr| typestr.match(/optional|required/i) }
+      specifier = Array(types).detect { |typestr| typestr.match(RE_REQUIRED_OPTIONAL) }
 
       if specifier
         types.delete(specifier)
 
-        return true if specifier.downcase == 'required'
-        return false if specifier.downcase == 'optional'
+        if specifier.downcase == 'required'
+          return true
+        elsif specifier.downcase == 'optional'
+          return false
+        end
       end
 
       strict
     end
 
-    def parse_accepted_values(types, text)
-      str = if types.last.match(RE_ARRAY_TYPE)
+    def parse_accepted_values(types=[], text='')
+      # values specified after the type, i.e.:
+      #
+      #   @argument [String, ["S","M","L"]] size
+      #
+      str = if Array(types).any? && types.last.match(RE_ARRAY_TYPE)
         types.pop
-      elsif text.match(RE_ACCEPTED_VALUES_STR)
+      # otherwise, look for them in the docstring, e.g.:
+      #
+      #   @argument [String] size
+      #    Accepts ["S","M","L"]
+      #
+      elsif text && text.match(RE_ACCEPTED_VALUES_STR)
         $1
       end
 
       if str
         begin
-          YAML.load(str)
+          # some people prefer to use the pipe (|) to separate the values
+          YAML.load(str.to_s.gsub('|', ','))
         rescue Exception => e
           YARD::APIPlugin.on_error <<-Error
             Unable to parse accepted values for @argument tag.
-            Error: #{exception}
+            Error:
+            #{e.class}: #{e.message}
             Offending docstring:
             #{text}
+            Accepted values string: '#{str}'
           Error
 
           return nil

data/lib/yard-api/tags.rb

@@ -16,4 +16,5 @@ YARD::Tags::Library.define_tag("API empty response", :no_content)
 YARD::Tags::Library.define_tag("API error", :throws)
 YARD::Tags::Library.define_tag("API warning", :warning)
 YARD::Tags::Library.define_tag("API note", :note)
-YARD::Tags::Library.define_tag("API message", :emits)
+YARD::Tags::Library.define_tag("API message", :emits)
+YARD::Tags::Library.define_tag("API model", :model)

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

@@ -85,7 +85,7 @@ module YARD::Templates::Helpers::BaseHelper
   def lookup_appendix(title)
     appendix = nil
 
-    puts "Looking up appendix: #{title}" if api_options.verbose
+    YARD::APIPlugin.log("Looking up appendix: #{title}") if api_options.verbose
 
     if object
       # try in the object scope

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.gsub(' ', '_').underscore
+    str.split("\n")[0].gsub(' ', '_').underscore
   end
 
   def url_for_file(filename, anchor = nil)
@@ -12,55 +12,53 @@ module YARD::Templates::Helpers::HtmlHelper
   end
 
   def static_pages()
-    return @static_pages if @static_pages
+    @@static_pages ||= begin
+      locate_static_pages(YARD::APIPlugin.options)
+    end
+  end
 
-    options = YARD::APIPlugin.options
+  def locate_static_pages(options)
+    title_overrides = {}
 
     paths = Array(options.static).map do |entry|
       pages = if entry.is_a?(Hash)
-        glob = entry['glob']
-        blacklist = Array(entry['exclude'])
-
-        unless glob
-          raise "Invalid static page entry, expected Hash to contain a 'glob' parameter: #{entry}"
+        if !entry.has_key?('path')
+          raise "Static page entry must contain a 'path' parameter: #{entry}"
+        elsif !entry.has_key?('title')
+          raise "Static page entry must contain a 'title' parameter: #{entry}"
         end
 
-        pages = Dir.glob(entry['glob'])
-
-        if blacklist.any?
-          pages.delete_if { |p| blacklist.any? { |filter| p.match(filter) } }
-        end
+        title_overrides[entry['path']] = entry['title']
 
-        pages
+        entry['path']
       elsif entry.is_a?(Array)
         entry.map(&:to_s)
       elsif entry.is_a?(String)
-        [ entry ]
+        entry
       end
-    end.flatten.compact.uniq.map { |path| File.join(options.source, path) }
+    end
 
-    markdown_exts = YARD::Templates::Helpers::MarkupHelper::MARKUP_EXTENSIONS[:markdown]
-    readme_page = options.readme
-    pages = Dir.glob(paths)
+    pages = Dir.glob(paths.flatten.compact)
 
-    if readme_page.present? && !options.one_file
-      pages.delete_if { |page| page.match(readme_page) }
+    if options.readme && !options.one_file
+      pages.delete_if { |page| page.match(options.readme) }
     end
 
-    @static_pages = pages.map do |page|
+    pages.uniq.map do |page|
       filename = 'file.' + File.split(page).last.sub(/\..*$/, '.html')
 
-      # extract page title if it's a markdown document; title is expected to
-      # be an h1 on the very first line:
-      title = if markdown_exts.include?(File.extname(page).sub('.', ''))
-        (File.open(page, &:gets) || '').strip.sub('# ', '')
-      else
-        # otherwise we'll just sanitize the file name
-        File.basename(page).sub(/\.\w+$/, '').gsub(/\W/, ' ').gsub(/\s+/, ' ').capitalize
-      end
+      title = (
+        title_overrides[page] ||
+        File.basename(page)
+          .sub(/\.\w+$/, '')
+          .gsub('_', ' ')
+          .gsub(/\W/, ' ')
+          .gsub(/\s+/, ' ')
+          .capitalize
+      )
 
       if options.verbose
-        puts "Serializing static page #{page}"
+        puts "Serializing static page #{page} (#{title})"
       end
 
       {
@@ -68,8 +66,9 @@ module YARD::Templates::Helpers::HtmlHelper
         filename: filename,
         title: title
       }
-    end
+    end.sort_by { |page| page[:title] }
   end
+  protected :locate_static_pages
 
   # override yard-appendix link_appendix
   def link_appendix(ref)

data/lib/yard-api/verifier.rb

@@ -10,9 +10,10 @@ module YARD
         relevant = list.select { |o| relevant_object?(o) }
 
         if @verbose && relevant.any?
-          puts "#{relevant.length}/#{list.length} objects are relevant:"
+          log "#{relevant.length}/#{list.length} objects are relevant:"
+
           relevant.each do |object|
-            puts "\t- #{object.path}"
+            log "\t- #{object.path}"
           end
         end
 
@@ -24,11 +25,22 @@ module YARD
         when :root, :module, :constant
           false
         when :method, :class
-          !object.tags('API').empty? && object.tags('internal').empty?
+          is_api = !object.tags('API').empty?
+          is_internal = !object.tags('internal').empty?
+
+          if @verbose && !is_api && !is_internal
+            log "Resource #{object} will be ignored as it contains no @API tag."
+          end
+
+          is_api && !is_internal
         else
           object.parent.nil? && relevant_object?(object.parent)
         end
       end
+
+      def log(*args)
+        ::YARD::APIPlugin.log(*args)
+      end
     end
   end
 end

data/lib/yard-api/version.rb

@@ -1,5 +1,5 @@
 module YARD
   module APIPlugin
-    VERSION = "0.1.10"
+    VERSION = "0.2.1"
   end
 end

data/lib/yard-api/yardoc_task.rb

@@ -14,7 +14,7 @@ module YARD::APIPlugin
       @config = load_config
       t = self
 
-      YARD::APIPlugin.options.update(@config)
+      api_options = YARD::APIPlugin.options.update(@config)
 
       t.verifier = YARD::APIPlugin::Verifier.new(config['verbose'])
       t.before = proc { FileUtils.rm_rf(config['output']) }
@@ -41,8 +41,11 @@ module YARD::APIPlugin
       set_option('verbose') if config['verbose']
       set_option('debug') if config['debug']
 
+      set_option('no-save') if config['no_save']
+      set_option('format', config['format'] || 'html')
+
       get_assets(config).each_pair do |asset_id, rpath|
-        asset_path = File.join(config['source'], rpath)
+        asset_path = rpath
 
         if File.directory?(asset_path)
           set_option 'asset', [ asset_path, asset_id ].join(':')
@@ -62,7 +65,7 @@ module YARD::APIPlugin
     private
 
     def load_config
-      path = Rails.root.join('config', 'yard_api.yml')
+      path = ENV.fetch('YARD_API_CONFIG') { Rails.root.join('config', 'yard_api.yml') }
 
       # load defaults
       config = YAML.load_file(File.join(YARD::APIPlugin::CONFIG_PATH, 'yard_api.yml'))
@@ -78,4 +81,4 @@ module YARD::APIPlugin
       config['assets'] || {}
     end
   end
-end
+end

data/lib/yard-api.rb

@@ -39,9 +39,9 @@ module YARD
 
     def self.on_error(message)
       if self.options.strict
-        raise error
+        raise message
       else
-        self.log(error, ::Logger::WARN)
+        self.log(message, ::Logger::WARN)
       end
     end
   end

data/spec/spec_helper.rb

@@ -108,6 +108,7 @@ RSpec.configure do |config|
       @options.send("#{key}=", value)
     end
 
+    @options.reset_defaults
     @overridden_options.clear
   end
 end

data/spec/tags/argument_spec.rb

@@ -16,7 +16,6 @@ describe YARD::APIPlugin::Tags::ArgumentTag do
   end
 
   it 'should work like an @attr tag' do
-        ENV['DO'] = '1'
     populate <<-'eof'
       # @argument [String] name
       #   Your full name.

data/templates/api/appendix/json/setup.rb

@@ -0,0 +1,25 @@
+# include T('default/appendix/html')
+
+def init
+  super
+end
+
+def appendix
+  controllers = options[:controllers]
+
+  if options[:all_resources]
+    controllers = options[:resources].flatten.select { |o|
+      o.is_a?(YARD::CodeObjects::NamespaceObject)
+    }
+  end
+
+  unless controllers && controllers.is_a?(Array)
+    return
+  end
+
+  @appendixes = controllers.collect do |controller|
+    controller.children.select { |tag| :appendix == tag.type }
+  end.flatten.uniq
+
+  super
+end

data/templates/api/docstring/json/setup.rb

@@ -0,0 +1,4 @@
+def init
+  puts "> HI from docstring!"
+  # sections :text, T('tags')
+end

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

@@ -5,7 +5,7 @@ include YARD::Templates::Helpers::FilterHelper
 
 def init
   options[:resources] = options[:objects].
-    group_by { |o| o.tags('API').first.text }.
+    group_by { |o| o.tags('API').first.text.split("\n").first }.
     sort_by  { |o| o.first }
 
   build_json_objects_map

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

@@ -0,0 +1,112 @@
+require 'pathname'
+
+include YARD::Templates::Helpers::ModuleHelper
+include YARD::Templates::Helpers::FilterHelper
+include YARD::Templates::Helpers::HtmlHelper
+
+RouteHelper = YARD::Templates::Helpers::RouteHelper
+
+def init
+  resources = options[:objects]
+    .group_by { |o| o.tags('API').first.text }
+    .sort_by  { |o| o.first }
+    .each { |resource, controllers| serialize_resource(resource, controllers) }
+end
+
+def serialize_resource(resource, controllers)
+  Templates::Engine.with_serializer("#{topicize resource}.json", options[:serializer]) do
+    JSON.pretty_generate({
+      object: resource,
+      api_objects: controllers.map do |controller|
+        dump_api_objects(controller)
+      end.flatten,
+      methods: method_details_list(controllers)
+    })
+  end
+end
+
+def method_details_list(controllers)
+  @meths = controllers.map do |controller|
+    controller.meths(:inherited => false, :included => false)
+  end.flatten
+
+  @meths = run_verifier(@meths)
+
+  @meths.map do |object, i|
+    dump_object(object).tap do |object_info|
+      object_info[:tags] = dump_object_tags(object)
+    end
+  end
+end
+
+def dump_api_objects(controller)
+  (controller.tags(:object) + controller.tags(:model)).map do |obj|
+    name, schema = obj.text.split(%r{\n+}, 2).map(&:strip)
+
+    {
+      controller: controller.name,
+      name: name,
+      schema: schema
+    }
+  end
+end
+
+def dump_object(object)
+  {
+    name: object.name,
+    route: get_route(object),
+    title: object.title,
+    type: object.type,
+    path: object.path,
+    namespace: object.namespace.path,
+    source: object.source,
+    source_type: object.source_type,
+    signature: object.signature,
+    files: object.files,
+    docstring: object.base_docstring,
+    dynamic: object.dynamic,
+    group: object.group,
+    visibility: object.visibility
+  }
+end
+
+def dump_object_tags(object)
+  object.tags.map do |tag|
+    tag.instance_variables.reduce({}) do |out, var|
+      key = var.to_s.sub('@', '')
+
+      if tag.respond_to?(key) && key != 'object'
+        out[key] = tag.send(key)
+      end
+
+      out
+    end
+  end
+end
+
+def get_route(object)
+  controller = object.parent.path.underscore
+  controller.sub!("_controller", '') unless controller.include?('/')
+
+  action = object.path.sub(/^.*#/, '')
+  action = action.sub(/_with_.*$/, '')
+  routes = RouteHelper.api_methods_for_controller_and_action(controller, action)
+  route = routes.first
+
+  if route.present?
+    # controller_path = "app/controllers/#{route.requirements[:controller]}_controller.rb"
+    # controller_path = nil unless File.file?(Rails.root+controller_path)
+
+    route_path = route.path.spec.to_s.gsub("(.:format)", "")
+    verb = if route.verb.source =~ /\^?(\w*)\$/
+      $1.upcase
+    else
+      route.verb.source
+    end
+
+    {
+      path: route_path,
+      verb: verb
+    }
+  end
+end

data/templates/api/layout/json/layout.erb

@@ -0,0 +1 @@
+<%= yieldall %>

data/templates/api/layout/json/setup.rb

@@ -0,0 +1,10 @@
+def init
+  puts "> LAYOUT"
+  # puts options[:object]
+
+  if options[:controllers]
+    sections :layout, [T('topic'), T('appendix')]
+  else
+    sections :layout, [:contents]
+  end
+end

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

@@ -1,13 +1,24 @@
-<div class="method_details <%= @index == 0 ? 'first' : '' %>">
-  <h2 class='api_method_name' name='<%= @method_link %>' data-subtopic='<%= @subtopic %>'>
-    <a name='<%= @method_link %>' href='#<%= @method_link %>'>
-      <%= object.tag("API").try(:text) %>
+<div class='method_details'>
+  <h2
+    class='api_method_name'
+    name='<%= @props[:method_link] %>'
+    data-subtopic='<%= @props[:subtopic] %>'
+  >
+    <a
+      name='<%= @props[:method_link] %>'
+      href='#<%= @props[:method_link] %>'
+    >
+      <%= object.tag('API').text %>
     </a>
 
-    <% if @controller_path && !api_options.github_url.to_s.empty? %>
+    <% if @props[:path] && !api_options.github_url.to_s.empty? %>
       <span class='defined-in'>
-        <a href="<%= api_options.github_url %>/blob/<%= api_options.github_branch %>/<%= @controller_path %>"><%= "#{@route.requirements[:controller].camelize}Controller\##{@route.requirements[:action]}" %></a></span>
+        <a href="<%= api_options.github_url %>/blob/<%= api_options.github_branch %>/<%= @props[:path] %>">
+          <%= "#{@props[:controller]}Controller\##{@props[:action]}" %>
+        </a>
+      </span>
     <% end %>
   </h2>
+
   <%= yieldall %>
 </div>

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

@@ -1,19 +1,13 @@
-<% @routes.each do |route| %>
-  <% route_path = route.path.spec.to_s.gsub("(.:format)", "")
-     if route.verb.source =~ /\^?(\w*)\$/
-       verb = $1.upcase
-     else
-       verb = route.verb.source
-     end
-   %>
+<% @props[:routes].each do |route| %>
+  <%
+    formatted_route_path = route[:path].split('/').map do |fragment|
+      is_id = fragment =~ /^\:[\w|_]+/
+      "<span #{'class="id-fragment"' if is_id}>#{fragment}</span>"
+    end.join('/')
+  %>
+
   <h3 class='endpoint'>
-    <span class="verb <%= verb.downcase %>"><%= verb %></span>
-    <%
-      formatted_route_path = route_path.split('/').map do |fragment|
-        is_id = fragment =~ /^\:[\w|_]+/
-        "<span #{'class="id-fragment"' if is_id}>#{fragment}</span>"
-      end.join('/')
-    %>
+    <span class="verb <%= route[:verb].downcase %>"><%= route[:verb] %></span>
     <%= formatted_route_path %>
   </h3>
 <% end %>

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

@@ -1,35 +1,58 @@
 # require 'route_helper'
 
 RouteHelper = YARD::Templates::Helpers::RouteHelper
+
 def init
-  get_routes
   sections :header, [:method_signature, T('docstring')]
 end
 
 def header
-  get_routes
-  @subtopic = (object.parent.tag('subtopic') || object.parent.tag('API')).text
+  routes = get_current_routes
+
+  unless route = routes.first
+    ::YARD::APIPlugin.log(
+      "[error] Unable to find route for object: #{object}",
+      ::Logger::ERROR
+    )
 
-  unless route = @routes.first
-    puts "[error] Unable to find route for object: #{object}"
     return
   end
 
-  @method_link = "method.#{route.requirements[:controller]}.#{route.requirements[:action]}"
-  @beta = object.tag('beta') || object.parent.tag('beta')
+  @props = {}
+  @props[:method_link] = [
+    'method',
+    route.requirements[:controller],
+    route.requirements[:action]
+  ].join('.')
+
+  @props[:subtopic] = (object.parent.tag('subtopic') || object.parent.tag('API')).text
+
+  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
+    @props[:action] = route.requirements[:action]
+  end
+
+  @props[:routes] = routes.map do |route|
+    {}.tap do |spec|
+      spec[:path] = route.path.spec.to_s.gsub("(.:format)", "")
+      spec[:verb] = route.verb.source =~ /\^?(\w*)\$/ ? $1.upcase : route.verb.source
+    end
+  end
+
   erb(:header)
 end
 
-def get_routes
-  @controller = object.parent.path.underscore
-  @controller.sub!("_controller", '') unless @controller.include?('/')
-
-  @action = object.path.sub(/^.*#/, '')
-  @action = @action.sub(/_with_.*$/, '')
-  @routes = RouteHelper.api_methods_for_controller_and_action(@controller, @action)
-  @route = @routes.first
-  if @route.present?
-    @controller_path = "app/controllers/#{@route.requirements[:controller]}_controller.rb"
-    @controller_path = nil unless File.file?(Rails.root+@controller_path)
-  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_.*$/, '')
+
+  RouteHelper.api_methods_for_controller_and_action(controller_name, action)
 end

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

@@ -0,0 +1,9 @@
+def init
+  sections :main
+end
+
+def main
+  {
+    text: object.tag("API").try(:text)
+  }
+end

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

@@ -1,28 +1,20 @@
 <ul class="argument">
   <% @argument_tags.each do |tag| %>
-    <%
-      tag.text ||= ''
-      desc = tag.text.strip.sub(/^\[([^\]]+)\]/, '').strip
-      type = $1
-      desc = desc.sub(/(\(optional\))/, '').strip
-      is_optional = $1.present?
-      name, desc = desc.split(/\s/, 2).map(&:strip)
-      desc = desc.sub(/[A|a]ccepted values:\s*\[([^\]]+)\]/, '').strip
-      accepted_values = $1
-    %>
     <li>
-      <code class="argument-name"><%= h name %></code>
-      <span class="argument-type"><%= type %></span>
-      <span class="argument-values fade">
-        <em><%= "[#{accepted_values}]" if accepted_values.present? %></em>
-      </span>
+      <code class="argument-name"><%= h tag.unscoped_name %></code>
+      <span class="argument-type"><%= tag.type %></span>
+      <% if (tag.accepted_values || []).any? %>
+        <span class="argument-values fade">
+          <em>[ <%= tag.accepted_values.join(', ') %> ]</em>
+        </span>
+      <% end %>
 
-      <% unless is_optional %>
+      <% if tag.is_required %>
         <em class="argument-required">Required</em>
       <% end %>
 
-      <% if !desc.empty? %>
-        <%= html_markup_markdown(desc) %>
+      <% if !tag.text.empty? %>
+        <%= html_markup_markdown(tag.text) %>
       <% end %>
     </li>
   <% end %>

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

@@ -1,9 +1,11 @@
+<% has_accepted_values = @argument_tags.any? { |e| Array(e.accepted_values).any? } %>
+
 <table>
   <thead>
     <tr>
       <th>Name</th>
       <th>Type</th>
-      <th>Accepted Values</th>
+      <% if has_accepted_values %><th>Accepted Values</th><% end %>
       <th>Required?</th>
       <th>Description</th>
     </tr>
@@ -14,13 +16,16 @@
       <tr>
         <td><code class="argument-name"><%= h tag.unscoped_name %></code></td>
         <td><span class="argument-type"><%= tag.type %></span></td>
-        <td>
-          <ul class="argument-values">
-            <% (tag.accepted_values || []).each do |value| %>
-              <li><%= value %></li>
-            <% end %>
-          </ul>
-        </td>
+        
+        <% if has_accepted_values %>
+          <td>
+            <ul class="argument-values">
+              <% (tag.accepted_values || []).each do |value| %>
+                <li><%= value %></li>
+              <% end %>
+            </ul>
+          </td>
+        <% end %>
 
         <td>
           <% if tag.is_required %>

data/templates/api/tags/setup.rb

@@ -1,5 +1,6 @@
 def init
   super
+
   sections *[
     :emits,
     :note,

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

@@ -1,3 +1,5 @@
+require 'json'
+
 def init
   sections :header, [:topic_doc, :method_details_list, [T('method_details')]]
   @resource = object
@@ -19,16 +21,17 @@ def topic_doc
 end
 
 def properties_of_model(json)
-  require 'json'
-  JSON::parse(json)['properties']
-rescue JSON::ParserError
-  nil
+  begin
+    JSON::parse(json || '')['properties']
+  rescue JSON::ParserError
+    nil
+  end
 end
 
 def word_wrap(text, col_width=80)
-   text.gsub!( /(\S{#{col_width}})(?=\S)/, '\1 ' )
-   text.gsub!( /(.{1,#{col_width}})(?:\s+|$)/, "\\1\n" )
-   text
+  text.gsub!( /(\S{#{col_width}})(?=\S)/, '\1 ' )
+  text.gsub!( /(.{1,#{col_width}})(?:\s+|$)/, "\\1\n" )
+  text
 end
 
 def indent(str, amount = 2, char = ' ')
@@ -36,7 +39,7 @@ def indent(str, amount = 2, char = ' ')
 end
 
 def render_comment(string, wrap = 75)
-  indent(word_wrap(string), 2, '/')
+  string ? indent(word_wrap(string), 2, '/') : ''
 end
 
 def render_value(value, type = 'string')

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

@@ -0,0 +1,25 @@
+def init
+  # sections :header, [:topic_doc, :method_details_list, [T('method_details')]]
+  sections :method_details_list, [T('method_details')]
+  @resource = object
+  # @beta = options[:controllers].any? { |c| c.tag('beta') }
+  puts "Topic: HEE? #{@resource}"
+end
+
+def method_details_list
+  @meths = options[:controllers].map { |c| c.meths(:inherited => false, :included => false) }.flatten
+  @meths = run_verifier(@meths)
+
+  # puts "Methods: #{@meths}"
+
+  buffer = [];
+
+  @meths.each_with_index do |meth, i|
+    # puts "#{i} => #{meth.tags}"
+    buffer.push(yieldall :object => meth, :index => i)
+  end
+
+  puts "Buffer: #{buffer.to_json}"
+
+  buffer.to_json
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: yard-api
 version: !ruby/object:Gem::Version
-  version: 0.1.10
+  version: 0.2.1
 platform: ruby
 authors:
 - Ahmad Amireh
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-09-16 00:00:00.000000000 Z
+date: 2015-07-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: yard
@@ -93,8 +93,10 @@ files:
 - spec/tags/argument_spec.rb
 - tasks/yard_api.rake
 - templates/api/appendix/html/setup.rb
+- templates/api/appendix/json/setup.rb
 - templates/api/docstring/html/setup.rb
 - templates/api/docstring/html/text.erb
+- templates/api/docstring/json/setup.rb
 - templates/api/fulldoc/html/css/common.css
 - templates/api/fulldoc/html/css/highlight.css
 - templates/api/fulldoc/html/js/highlight.zip
@@ -157,6 +159,7 @@ files:
 - templates/api/fulldoc/html/js/highlight/styles/zenburn.css
 - templates/api/fulldoc/html/js/jquery-1.11.1.min.js
 - templates/api/fulldoc/html/setup.rb
+- templates/api/fulldoc/json/setup.rb
 - templates/api/layout/html/_dynamic_styles.erb
 - templates/api/layout/html/footer.erb
 - templates/api/layout/html/headers.erb
@@ -164,9 +167,12 @@ files:
 - templates/api/layout/html/scripts.erb
 - templates/api/layout/html/setup.rb
 - templates/api/layout/html/sidebar.erb
+- templates/api/layout/json/layout.erb
+- templates/api/layout/json/setup.rb
 - templates/api/method_details/html/header.erb
 - templates/api/method_details/html/method_signature.erb
 - templates/api/method_details/html/setup.rb
+- templates/api/method_details/json/setup.rb
 - templates/api/onefile/html/setup.rb
 - templates/api/onefile/html/sidebar.erb
 - templates/api/tags/html/_example_code_block.erb
@@ -189,6 +195,7 @@ files:
 - templates/api/topic/html/method_details_list.erb
 - templates/api/topic/html/setup.rb
 - templates/api/topic/html/topic_doc.erb
+- templates/api/topic/json/setup.rb
 - yard-api.gemspec
 homepage: https://github.com/amireh/yard-api
 licenses: