yard-api 0.1.4 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 4a4a3b1beee6e7ade875e7a95004d14da25fb0d7
-  data.tar.gz: ea2078d3f6d4ecf6afdc91aa635ebf53cb046343
+  metadata.gz: c4a7dbe342296a08ff5f47833f80909d984d0607
+  data.tar.gz: 278a23bc1ba6409da13fa24b7c755b19a0a38d09
 SHA512:
-  metadata.gz: eeb5f091e4cd539126f6fd69dd93186b9e7ef5ab9f417cf588c25b48fc979585c1b18c4d5bdc0345af656b0d0812c7c7132ef558719622b111c687c85f9e6316
-  data.tar.gz: adb5d639749e0544ef05234636cbe666459a9dc6bfc9fae9c239a25e796ea4539c1b343e4e4a648d81fb8039bd398cb7e0cfc2dd10a14a7b3eb4f288b9944782
+  metadata.gz: 4fcbd79b911d4e108f36a5dbdc8bb52457ed88b12c4324350d71da1c7c48e84e821ccc910c94297843b12004473861be20b5252418f6f80c4539399868f8a970
+  data.tar.gz: 2d4c8731cf3ac058083028f433113cb2b9f41ef7603506f831329cdb1f7449532d4df9fc3b13702462023df2d065297d5cf87abe8d3262ee781f87807f771187

data/README.md

@@ -8,12 +8,28 @@ TODO
 
 TODO
 
+## Configuration
+
+`yard-api` will look for a file in `config/yard_api.yml` in the Rails root for customizations. Configuration fields not specified in that file will be filled with the default values found in [config/yard_api.yml](https://github.com/amireh/yard-api/blob/master/config/yard_api.yml).
+
+Read that file to view all the available options.
+
 ## Notes
 
 - can only document classes and class methods; modules, root objects, and constants are ignored
 
 ## Changelog
 
+**15/9/2014**
+
+- `@argument` tags can now be formatted in a table by setting the `tabular_arguments` option to true
+- `@argument_scope`: a new tag that improves the formatting of endpoint arguments that are scoped by a common prefix (e.g, nested inside a json object), like `user[name]` => `name`
+- `@argument` can now parse accepted values in two formats; inline within the types array, or by explicitly writing it in the tag text using any of `Accepted values: [...]`, `Accepts: [...]`, or `Possible values: [...]`
+- A new option: `strict_arguments` that provides a default for the `is_required` property of `@argument` tags. This default is used if the tag does not explicitly state `Optional` or `Required` in its type specifier.
+- Support for dynamic javascript and style code based on options. See `templates/layout/setup.rb#inline_{javascripts,stylesheets}`
+- A new set of options for customizing layout: `content_width`, `sidebar_width` and `spacer`
+- `github_url` and `github_branch` options for tuning api endpoint source links
+
 **14/9/2014**
 
 - Support for single-page output through the `one_file` option

data/lib/yard-api/options.rb

@@ -1,13 +1,18 @@
 module YARD::APIPlugin
+  # See config/yard_api.yml for documentation for the options.
   class Options < YARD::Options
     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, ''
+    default_attr :github_url, nil
+    default_attr :github_branch, 'master'
 
-    default_attr :footer_copyright, nil
-    default_attr :footer_note, nil
+    default_attr :footer_copyright, ''
+    default_attr :footer_note, ''
 
     default_attr :one_file, false
     default_attr :verbose, false
@@ -17,6 +22,10 @@ module YARD::APIPlugin
     default_attr :tabular_arguments, false
     default_attr :strict_arguments, false
 
+    default_attr :sidebar_width, 240
+    default_attr :content_width, 'fluid'
+    default_attr :spacer, 20
+
     attr_accessor :readme
   end
 end

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

@@ -92,6 +92,8 @@ module YARD::Templates::Helpers::HtmlHelper
   end
 
   def sidebar_link(title, href, options={})
+    options[:class_name] ||= (object == href ? 'active' : nil)
+
     <<-HTML
       <a href="#{url_for(href)}" class="#{options[:class_name]}">#{title}</a>
     HTML

data/lib/yard-api/version.rb

@@ -1,5 +1,5 @@
 module YARD
   module APIPlugin
-    VERSION = "0.1.4"
+    VERSION = "0.1.5"
   end
 end

data/lib/yard-api/yardoc_task.rb

@@ -9,6 +9,8 @@ module YARD::APIPlugin
     end
 
     def run
+      YARD::APIPlugin.options.reset_defaults
+
       @config = load_config
       t = self
 

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

@@ -0,0 +1,16 @@
+<style>
+  body {
+    padding-left: <%= api_options.sidebar_width + api_options.spacer %>px;
+    padding-right: <%= api_options.spacer %>px;
+  }
+
+  #sidebar {
+    width: <%= api_options.sidebar_width %>px;
+  }
+
+  <% if api_options.content_width.to_i > 0 %>
+    #content {
+      max-width: <%= api_options.content_width %>px;
+    }
+  <% end %>
+</style>

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

@@ -1,11 +1,9 @@
 <div id="footer">
   <p>
-    <% if api_options['footer_copyright'] %>
-      <%= api_options['footer_copyright'] %>
-    <% end %>
+    <%= api_options.footer_copyright.to_s %>
 
     Generated on <%= Time.now.strftime("%c") %>
   </p>
 
-  <%= api_options['footer_note'].to_s %>
+  <%= api_options.footer_note.to_s %>
 </div>

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

@@ -1,7 +1,7 @@
 <meta name="Content-Type" content="text/html;charset=UTF-8">
 <meta charset="UTF-8">
 
-<title><%= api_options['title'] %></title>
+<title><%= api_options.window_title || api_options.title %></title>
 
 <% stylesheets.each do |stylesheet| %>
   <link rel="stylesheet" href="<%= url_for(stylesheet) %>" type="text/css" charset="utf-8" />

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

@@ -2,16 +2,20 @@
 <html>
   <head>
     <%= erb(:headers) %>
+
+    <% inline_stylesheets.each do |style| %>
+      <%= erb(style) %>
+    <% end %>
   </head>
 
-  <body class="theme-<%= api_options.theme %>">
+  <body class="theme-<%= api_options.theme %> <%= 'onefile' if api_options.one_file %>">
     <div id="sidebar">
       <%= erb(:sidebar) %>
     </div>
 
     <% if options[:all_resources] %>
       <div id="content">
-        <% if api_options['one_file'] %>
+        <% if api_options.one_file %>
           <% static_pages.each do |page| %>
             <%= diskfile page[:src] %>
           <% end %>
@@ -27,5 +31,9 @@
 
     <%= erb(:footer) %>
     <%= erb(:scripts) %>
+
+    <% inline_javascripts.each do |script| %>
+      <%= erb(script) %>
+    <% end %>
   </body>
 </html>

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

@@ -20,11 +20,16 @@
   $(function() {
     var currentPage = location.pathname.match(/\/([^\/]+)$/)[1];
     var $page = $('#sidebar [href="' + currentPage + '"]');
-    if ($page.length === 0) {
-      $page = $('#sidebar a[href=""]');
+
+    if (!currentPage) {
+      return;
     }
 
-    $page.addClass('current');
+    // if ($page.length === 0) {
+    //   $page = $('#sidebar a[href=""]');
+    // }
+
+    // $page.addClass('active');
     console.log('Highlighting current page:', $page, currentPage);
   });
 

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

@@ -24,6 +24,10 @@ def stylesheets
   ]
 end
 
+def inline_stylesheets
+  [ '_dynamic_styles' ]
+end
+
 def javascripts
   %w[
     js/jquery-1.11.1.min.js
@@ -31,6 +35,10 @@ def javascripts
   ]
 end
 
+def inline_javascripts
+  []
+end
+
 def contents
   @contents
 end

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

@@ -4,8 +4,9 @@
       <%= object.tag("API").try(:text) %>
     </a>
 
-    <% if @controller_path %>
-      <span class='defined-in'><a href="https://github.com/amireh/pibi/blob/master/<%= @controller_path %>"><%= "#{@route.requirements[:controller].camelize}Controller\##{@route.requirements[:action]}" %></a></span>
+    <% if @controller_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>
     <% end %>
   </h2>
   <%= yieldall %>

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: yard-api
 version: !ruby/object:Gem::Version
-  version: 0.1.4
+  version: 0.1.5
 platform: ruby
 authors:
 - Ahmad Amireh
@@ -95,6 +95,7 @@ files:
 - templates/api/docstring/html/setup.rb
 - templates/api/docstring/html/text.erb
 - templates/api/fulldoc/html/setup.rb
+- templates/api/layout/html/_dynamic_styles.erb
 - templates/api/layout/html/footer.erb
 - templates/api/layout/html/headers.erb
 - templates/api/layout/html/layout.erb