yard-api 0.2.2 → 0.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 6ebf62e002470fba445a8cb1b434bd41cdebc2e6
-  data.tar.gz: 0170bf9ab9cb17ba47c9e6f9ecd08a1c0ce4ab8e
+  metadata.gz: ab2e2a361011adda668edbcad1b71ba857fe61ab
+  data.tar.gz: c3ed5abc5b2de588e9722179e97acbc4c044986a
 SHA512:
-  metadata.gz: 436c1737925db7af1753f0a77045baf474e26162b24187a396a339a74a71b9f5767cc0e73920c6e052b1b6fae7b0c3490e4719b164437b289f2e571805c43349
-  data.tar.gz: cff13bc7797c6870aec42885f5956c3078968c1ec39ea2cd4f9ec6470596cc4173fdb32f92d8aeddfdcd3a56603fe9bf434af29653f04074efb70fc9e0afbb04
+  metadata.gz: d81dc23669668ed42dfc44e15c317b6199ab4be26cecfbc690abc0ab58b1209c0b15a984dd302ca7f0de8c00153f4e102ee0c060a354241724fc054c7b270957
+  data.tar.gz: 936a31ac15cecde12085d147565e92f51edef9251370ef33d9488ba9aa25d82473d64f48ca756a1235a3e6dbbd3d3f56abcd03ce27079379164e689eaafda338

data/README.md

@@ -2,11 +2,9 @@
 
 [![Build Status](https://travis-ci.org/amireh/yard-api.png)](https://travis-ci.org/amireh/yard-api)
 
-TODO
-
 ## Usage
 
-TODO
+See [https://amireh.github.io/yard-api].
 
 ### Compatibility options
 
@@ -34,8 +32,23 @@ Read that file to view all the available options.
 
 - can only document classes and class methods; modules, root objects, and constants are ignored
 
+## Generating the docs for YARD-API
+
+1. go to the `gh-pages` branch, check it out if you haven't
+2. run `bin/generate-docs`
+3. browse `index.html`
+
 ## Changelog
 
+**28/7/2015 [0.2.3]**
+
+- dropped the `@argument_scope` tag
+- JSON is available as an output format now
+- added usage documentation, found at [http://amireh.github.io/yard-api]
+- added an example app
+- various style improvements
+- `@example_request` is now able to output a sample cURL command.
+
 **0.1.7**
 
 - new compatibility option `leading_argument_name_fix`

data/config/yard_api.yml

@@ -7,6 +7,9 @@ readme: doc/api/README.md
 # as in the layout as the primary heading.
 title: Rails API Project
 
+url_title: my_app
+url_prefix: /api
+
 # The resource index is a mega-index page that contains all the API resources.
 resource_index: true
 
@@ -100,4 +103,10 @@ spacer: 20
 #   @argument [Type specifier] name_specifier
 #
 # But that may not be viable in very large, existing projects.
-leading_argument_name_fix: false
+leading_argument_name_fix: false
+
+use_beta_flag: true
+use_beta_banner: false
+
+show_footer: true
+readme_page_title: Home

data/lib/yard-api/options.rb

@@ -5,6 +5,8 @@ module YARD::APIPlugin
     default_attr :no_save, false
 
     default_attr :title, 'Rails API Project'
+    default_attr :url_title, 'my_app'
+    default_attr :url_prefix, '/api'
     default_attr :window_title, 'Rails API Project Documentation'
     default_attr :version, ''
     default_attr :static, []
@@ -31,6 +33,12 @@ module YARD::APIPlugin
 
     default_attr :leading_argument_name_fix, false
 
+    default_attr :use_beta_flag, true
+    default_attr :use_beta_banner, false
+
+    default_attr :show_footer, true
+    default_attr :readme_page_title, 'Home'
+
     attr_accessor :readme
   end
 end

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

@@ -47,16 +47,6 @@ module YARD::APIPlugin::Tags
       end
     end
 
-    def unscoped_name
-      scope_tag = @object.tag(:argument_scope)
-
-      if scope_tag && @name =~ /^#{scope_tag.text.gsub(/\[\]/, '')}\[([^\]]+)\]$/
-        $1
-      else
-        @name
-      end
-    end
-
     private
 
     def parse_is_required(types=[])

data/lib/yard-api/tags.rb

@@ -2,7 +2,6 @@ require 'yard-api/tags/argument_tag'
 
 YARD::Tags::Library.define_tag("API endpoint", :API)
 YARD::Tags::Library.define_tag("API endpoint argument", :argument, YARD::APIPlugin::Tags::ArgumentTag)
-YARD::Tags::Library.define_tag("API endpoint argument scope", :argument_scope)
 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)

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

@@ -100,10 +100,25 @@ module YARD::Templates::Helpers::BaseHelper
     appendix
   end
 
-  def tag_partial(name, tag)
+  def tag_partial(name, tag, locals={})
     options[:tag] = tag
+    locals.each_pair { |key, value| options[key] = value }
     out = erb(name)
     options.delete(:tag)
+    locals.keys.each { |key| options.delete(key.to_sym) }
     out
   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)
+  end
+
+  def get_current_route
+    get_current_routes.first
+  end
 end

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

@@ -98,7 +98,14 @@ module YARD::Templates::Helpers::HtmlHelper
     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

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

@@ -15,5 +15,13 @@ module YARD::Templates::Helpers
       controller_path.gsub!(/^\/|_controller$/, '')
       @routes.find_all { |r| matches_controller_and_action?(r, controller_path, action) }
     end
+
+    def self.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
+    end
   end
 end

data/lib/yard-api/verifier.rb

@@ -25,14 +25,13 @@ module YARD
         when :root, :module, :constant
           false
         when :method, :class
-          is_api = !object.tags('API').empty?
-          is_internal = !object.tags('internal').empty?
+          return false if object.tags('internal').any?
 
-          if @verbose && !is_api && !is_internal
-            log "Resource #{object} will be ignored as it contains no @API tag."
+          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
           end
-
-          is_api && !is_internal
         else
           object.parent.nil? && relevant_object?(object.parent)
         end

data/lib/yard-api/version.rb

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

data/tasks/yard_api.rake

@@ -6,6 +6,7 @@ runner = YARD::APIPlugin::YardocTask.new
 desc 'generate YARD API docs'
 task :yard_api => :environment do |t|
   output = runner.config['output']
+  # TODO: make this compatible with json output format
   puts <<-Message
     API Documentation successfully generated in #{output}
     See #{output}/index.html

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

@@ -1,25 +1,4 @@
-# include T('default/appendix/html')
-
+# TODO
 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/fulldoc/html/css/common.css

@@ -2,33 +2,27 @@ body {
   font-family: "Open Sans", Calibri, Candara, "Helvetica Neue", Arial, sans-serif;
   font-size: 15px;
   line-height: 1.4;
-  margin: 0;
+  margin: 1em;
   padding: 0;
   color: #333;
 }
 
-a, #sidebar a:visited {
+a {
   color: #4183c4;
 }
-a:visited {
-  color: #8B3377;
+
+a:hover, a:focus {
+  text-decoration: none;
 }
-a:hover,
-a:focus,
-#sidebar a.current,
-#sidebar a:hover,
-#sidebar a:focus {
-  color: #99173C;
+
+a.active {
+  font-weight: bold;
 }
 
 #content {
   margin: 0 auto;
 }
 
-p, h4 {
-  margin: 0.8em 0;
-}
-
 code {
   margin: 0 2px;
   padding: 0px 5px;
@@ -42,93 +36,83 @@ code {
 h1 {
   font-size: 1.6em;
   padding: 0.6em 0;
-  margin: 10px 0;
-}
-#content h1 {
-  border-bottom: 1px solid #ddd;
+  margin: 0.6em 0;
 }
 
 h2 {
-  border-bottom: 1px #ddd solid;
-  padding: 0 0 3px;
   font-size: 1.4em;
-  margin-top: 30px;
+  padding: 0.6em 0;
+  margin: 0.6em 0;
 }
-h3.beta {
-  border: 1px solid black;
-  background-color: #E5E8FF;
-  text-align: center;
-  padding: 6px;
-  font-weight: bold;
+
+.endpoint__beta-banner {
+  border-left: 5px solid rgba(255,0,0,0.65);
+  background-color: #ffc;
+  padding: 0.6em;
+  font-size: 85%;
+}
+
+.method-details__beta-flag {
+  color: #CC0000;
+  background: #fca;
+  padding: 0.5em 0.6em;
+  font-size: 85%;
 }
+
 #sidebar {
   position: fixed;
   overflow: auto;
   bottom: 0;
   top: 0;
-  left: 0;
-  background: #f8f8f8;
-  border-right: 1px solid #ddd;
+  left: 1em;
 }
+
 #sidebar h1 {
   margin-bottom: 0;
-  margin-left: 20px;
   border-bottom: 1px solid #ddd;
 }
-#sidebar a,
-#sidebar h2 {
-  display:block;
-  border: none;
-  font-size: 1.1em;
-}
-#sidebar h2 {
-  padding: 10px 0;
-  font-size: 20px;
-  font-weight: normal;
-  text-transform: uppercase;
-  text-shadow: 0 1px 0 white;
-  margin: 0;
-}
-#sidebar h2.first {
-  border-top:none;
-}
-#sidebar h2,
-#sidebar a {
-  border-right: 5px solid transparent;
-}
+
 #sidebar a {
-  padding: 5px 0;
+  display: block;
+  color: inherit;
+  padding: 0.35em 0;
   text-decoration: none;
-  font-size: 13px;
-  font-weight: bold;
 }
 
-#content a[name^="method."] {
-  outline: none;
+#sidebar a:hover {
+  text-decoration: underline;
 }
-.method_details_list h2 {
+
+#sidebar a.active {
+  color: #4183c4;
 }
 
+.sidebar__heading {
+  color: #939da3;
+  text-transform: uppercase;
+  font-size: 1em;
+  margin-bottom: 0.5em;
+  padding-bottom: 0;
+  margin-top: 1em;
+}
 
-.method_details h3.endpoint {
-  font-size: 14px;
+.endpoint__path {
+  font-size: 90%;
   font-weight: normal;
   font-family: Monaco, Consolas, Courier, monospace;
-  padding: 6px 10px;
-  margin-top: 18px;
-  background: #f8f8f8;
-  border: 1px solid #ddd;
-  border-radius: 2px;
+  padding: 1em;
+  margin-top: 1em;
+  background: #ffc;
 }
 
-.method_details .verb {
+.method-details .verb {
   font-weight: bold;
 }
-.method_details .id-fragment {
+.method-details .id-fragment {
   color: #CC0000;
 }
 
-h2 .defined-in {
+.method-details__defined-in {
   float:right;
   font-size:10px;
   padding-top:10px;
@@ -137,32 +121,27 @@ h2 .defined-in {
 
 /* Footer */
 #footer {
-  margin-top: 20px;
-  margin-left: 180px;
-  border-top: 1px solid #ddd;
+  margin: 1em 0;
+  border-top: 1px solid #ccc;
   text-align: center;
-  color: #999;
+  color: #666;
+  font-size: 85%;
 }
 
 #footer a {
-  color: #999;
+  color: #666;
 }
 
-pre.code,
-div.syntaxhighlighter {
-  background-color: #f8f8f8;
-  border: 1px solid #ddd;
-  font-size: 13px;
-  line-height: 19px;
-  overflow: auto;
-  padding: 6px 10px;
-  border-radius: 3px;
+/* highlight.js overrides */
+pre.code, div.syntaxhighlighter {
   font-family: Monaco, Consolas, Courier, monospace;
+  background-color: #ffd;
+  font-size: 85%;
+  overflow: auto;
+  padding: 0.5em 1em;
 }
 
-.syntaxhighlighter .line code,
-pre.code code,
-.endpoint-errors code {
+.syntaxhighlighter .line code, pre.code code, .endpoint-errors code {
   white-space: nowrap;
   background: none;
   border: none;
@@ -171,6 +150,7 @@ pre.code code,
   padding: 0;
   border-radius: 0;
 }
+
 .syntaxhighlighter {
   overflow: auto;
 }
@@ -191,26 +171,15 @@ table#quicklinks th {
   padding: 12px;
 }
 
-h2.api_method_name a {
+a.method-details__name-link {
   text-decoration: none;
-  color: black;
+  color: inherit;
 }
 
 div.appendix img {
   max-width: 100%;
 }
 
-.argument-required {
-  font-style: normal;
-  color: #CC0000;
-}
-
-li .argument-required {
-  font-size: 12px;
-  padding: 2px 4px;
-  font-weight: bold;
-}
-
 .example-title {
   padding: 5px 0;
   font-size: 11px;
@@ -218,10 +187,6 @@ li .argument-required {
   color: #777;
 }
 
-.fade {
-  color: #777;
-}
-
 blockquote {
   border-left: 4px solid #DDD;
   padding: 0 15px;
@@ -279,3 +244,91 @@ hr {
 
 .emits-tag {
 }
+
+/* --------------------------------------------------------------------------
+ * ARGUMENTS
+ * -------------------------------------------------------------------------- */
+h4 {
+  margin: 2em 0;
+  padding: 1em 0;
+  border-bottom: 1px solid #ccc;
+  color: #666;
+}
+
+.argument-listing {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+}
+
+.argument-listing__argument {
+  padding: 0;
+  margin: 2em 0;
+  display: block;
+  min-height: 4em;
+}
+
+.argument-listing__argument-details {
+  /*display: inline-block;*/
+  width: 40%;
+  max-width: 260px;
+  text-align: right;
+  vertical-align: top;
+  float: left;
+}
+
+.argument-listing__argument-name,
+.argument-listing__argument-type,
+.argument-listing__argument-values,
+.argument-listing__argument-required {
+  display: block;
+}
+
+code.argument-listing__argument-name {
+  border: none;
+  padding: 0;
+  margin: 0;
+  overflow: auto;
+}
+
+/* fade these out to give more emphasis to the name */
+.argument-listing__argument-type,
+.argument-listing__argument-values,
+.argument-listing__argument-required {
+  font-size: 85%;
+  color: #777;
+}
+
+.argument-listing__argument-required {
+  font-style: normal;
+  color: #CC0000;
+  font-weight: bold;
+  opacity: 0.6;
+}
+
+.argument-listing__argument-text {
+  vertical-align: top;
+  margin-left: 1em;
+  margin-left: 260px;
+  padding-left: 1em;
+}
+
+.argument-listing__argument-text > p {
+  margin-top: 0;
+}
+
+.example-codeblocks__tabs {
+  margin-bottom: -0.5em; /* negate the margin of the example block */
+  background: #ffc;
+  padding: 0.5em 1em;
+  font-size: 85%;
+}
+
+.example-codeblocks__tab {
+  margin-right: 0.5em;
+  cursor: pointer;
+}
+
+.example-codeblocks__tabs a.active {
+  font-weight: bold;
+}