yardbird 0.0.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: c462a82143467e59909e2bb11fd44140f059fe78
+  data.tar.gz: e56a4d6754f264b887dd544b9d2d447b48375796
+SHA512:
+  metadata.gz: 9dcf3f085302c37755dea9461ef4ff6f6839c2e3bbc0a0fda15ea0b706f7d47f9bced024dabefe8935a85165142e7de668d01055a995650edf19b339e4d10c1f
+  data.tar.gz: 71349277759eec01bf424df58bf4b19aaf6dfae1f736c1ccebc8e206a126a2848ac41ad3dada9c4892600dcc802a22c1103a1c9bb81953cc5fda953e2823e75e

data/.gitignore

@@ -0,0 +1,22 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in yardbird.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Alexander Staubo
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,68 @@
+# Yardbird
+
+Documentation generator that uses Yardoc as the parser. It's suitable for both Sinatra and Rails applications.
+
+## Installation
+
+Install as a Rubygem:
+
+    sudo gem install yardbird
+
+Then run:
+
+    $ yardbird
+
+## Usage
+
+    $ yardbird generate myproject/ -o docs.md
+
+## Yardoc extensions
+
+Every API endpoint comment must start with `@apidoc`.
+
+### `@category <label>`
+
+Specify the category — a logic grouping — that the endpoint belongs.
+
+### `@path <path>`
+
+Specify the path to the endpoint.
+
+### `@method <method>`
+
+Specify the method. (Deprecated: `@http`.)
+
+### `@optional [<type>] <name> <description>`
+
+Specify optional parameter. May be repeated.
+
+### `@required [<type>] <name> <description>`
+
+Specify required parameter. May be required.
+
+### `@example <path and query>`
+
+Give example endpoint usage.
+
+### `@status <code> <description>`
+
+Describe response status. May be repeated.
+
+## Example comment
+
+    # @apidoc
+    # Returns a list of all agents.
+    #
+    # @category Agents
+    # @path /api/v1/agents
+    # @http GET
+    # @required [boolean] featured Return featured agents only.
+    # @optional [integer] offset Return agents from the given offset.
+    # @optional ['yyyy-mm-ddThh:mm'] after Return all agents created after the given date.
+    # @status 403 If basic auth username is not 'api' or password is incorrect
+    # @status 400 If an invalid parameter is provided.
+    # @example /api/v1/agents?featured=true&offset=200&limit=100&before=2014-04-16&after=2014-01-01
+    #
+    get '/agents' do
+      ...
+    end

data/Rakefile

@@ -0,0 +1,2 @@
+require "bundler/gem_tasks"
+

data/bin/yardbird

@@ -0,0 +1,31 @@
+#!/usr/bin/env ruby
+
+require 'mercenary'
+
+require_relative '../lib/yardbird'
+
+Mercenary.program(:yardbird) do |p|
+  p.version Yardbird::VERSION
+  p.description 'Yardbird extracts REST API comments as a Markdown document'
+  p.syntax "yardbird <subcommand> [options]"
+
+  p.command :generate do |c|
+    c.syntax "generate PATH"
+    c.description "Generates from PATH"
+    c.option :outfile, '-o TARGET', '--out TARGET', 'Write to TARGET. Defaults to standard output.'
+    c.option :section_level, '--start-section LEVEL', 'Begin sections at level LEVEL. Default is 0.', Integer
+
+    c.action do |args, options|
+      abort "Specify a path." if args.empty?
+      if (file = options[:outfile])
+        stream = File.open(file, 'w:utf-8')
+      else
+        stream = $stdout
+      end
+      generator = Yardbird::Generator.new
+      generator.section_level = options[:section_level]
+      generator.paths |= args
+      generator.generate(stream)
+    end
+  end
+end

data/lib/yardbird.rb

@@ -0,0 +1,5 @@
+require_relative 'yardbird/version'
+require_relative 'yardbird/endpoint'
+require_relative 'yardbird/parser'
+require_relative 'yardbird/generator'
+require_relative 'yardbird/writer'

data/lib/yardbird/endpoint.rb

@@ -0,0 +1,61 @@
+require 'active_support/core_ext/object/try'
+
+module Yarddown
+
+  class Endpoint
+
+    attr_accessor :method,
+      :path,
+      :docstring,
+      :params,
+      :example,
+      :example_params,
+      :category,
+      :status
+
+    def initialize(yardoc)
+      @yardoc = yardoc
+      parse
+    end
+
+    def parse
+      self.method = @yardoc.tags(:http)[0].try(:text)
+      self.method ||= 'GET'
+
+      self.path   = @yardoc.tags(:path)[0].try(:text)
+      self.docstring = @yardoc.docstring
+      if @yardoc.tags(:category).any?
+        self.category = @yardoc.tags(:category)[0].try(:text)
+      else
+        self.category = 'Uncategorized'
+      end
+      self.status = @yardoc.tags(:status).map do |s|
+        {
+          code: s.name.to_i,
+          doc: s.text
+        }
+      end
+      self.status = self.status.sort_by { |s| s[:code] }
+      self.params = [@yardoc.tags(:required), @yardoc.tags(:optional)].flatten.map do |param|
+        {
+          name: param.name,
+          types: param.types,
+          doc: param.text,
+          type: param.tag_name
+        }
+      end
+
+      self.example = @yardoc.tags(:example)[0].try(:name)
+      self.example ||= self.path
+      if @yardoc.tags(:example)[0].try(:text)
+        self.example_params = @yardoc.tags(:example)[0].text.split.map {|p| p.split(':')}
+      end
+    end
+
+    def doc_path
+      "#{path}.#{method}"
+    end
+
+  end
+
+end

data/lib/yardbird/generator.rb

@@ -0,0 +1,99 @@
+# encoding: utf-8
+
+require_relative './endpoint'
+require_relative './parser'
+require_relative './writer'
+
+require 'active_support/core_ext/object/blank'
+
+module Yardbird
+  class Generator
+
+    attr_accessor :paths
+    attr_accessor :options
+    attr_accessor :section_level
+
+    def initialize(options = {})
+      @paths = []
+    end
+
+    def generate(stream)
+      endpoints = Yarddown::Parser.parse(@paths)
+
+      grouped_by_category = endpoints.group_by { |e| e.category }
+
+      writer = Writer.new(stream, section_level: @section_level)
+
+      writer.line "<section id='toc'>"
+      writer.section "Table of Contents" do
+        categories = grouped_by_category.keys.uniq.sort_by { |s| s.downcase }
+        categories.each do |category|
+          writer.bullet "[#{category}](##{category_anchor_name(category)})"
+          writer.indent(2) do
+            eps = grouped_by_category[category]
+            eps.each do |ep|
+              writer.bullet "[`#{ep.method} #{ep.path}`](##{endpoint_anchor_name(ep)})"
+            end
+          end
+        end
+      end
+      writer.line "</section>"
+
+      grouped_by_category.each do |category, eps|
+        writer.heading category, anchor: category_anchor_name(category)
+        writer.section do
+          eps.each do |ep|
+            writer.heading "`#{ep.method} #{ep.path}`", anchor: endpoint_anchor_name(ep)
+            writer.section do
+              writer.line ep.docstring
+              if ep.params.any?
+                writer.heading "Parameters"
+                writer.section do
+                  ep.params.each do |param|
+                    writer.line "`#{param[:name]}` (",
+                      [param[:types]].flatten.join(', '),
+                      param[:type] == 'required' ? ", **required**" : '',
+                      ")<br/>#{param[:doc]}"
+                    writer.blank
+                  end
+                end
+              end
+              if ep.status.present?
+                writer.heading "Status Codes"
+                writer.section do
+                  ep.status.each do |s|
+                    writer.line "**#{s[:code]}** — #{s[:doc]}"
+                    writer.blank
+                  end
+                end
+              end
+              if ep.example.present?
+                writer.heading "Example"
+                writer.code_block do
+                  writer.line "#{ep.method} #{ep.example} HTTP/1.1"
+                end
+              end
+            end
+          end
+        end
+      end
+
+      writer.flush
+      stream
+    end
+
+    private
+
+      def category_anchor_name(category)
+        category.downcase
+      end
+
+      def endpoint_anchor_name(endpoint)
+        [endpoint.category, endpoint.method, endpoint.path.gsub(/[\/:]/, '-')].
+          join('-').
+          gsub(/-+/, '-').
+          downcase
+      end
+
+  end
+end

data/lib/yardbird/parser.rb

@@ -0,0 +1,30 @@
+require 'yard'
+
+YARD::Config.load_plugin("sinatra")
+
+YARD::Tags::Library.define_tag("API Doc", :apidoc)
+YARD::Tags::Library.define_tag("Endpoint path", :path)
+YARD::Tags::Library.define_tag("Category", :category)
+YARD::Tags::Library.define_tag("API example", :example, :with_name)
+YARD::Tags::Library.define_tag("HTTP verb", :http)
+YARD::Tags::Library.define_tag("Return status", :status, :with_name)
+YARD::Tags::Library.define_tag("Required param", :required, :with_types_and_name)
+YARD::Tags::Library.define_tag("Optional param", :optional, :with_types_and_name)
+
+module Yarddown
+
+  class Parser
+    def self.parse(paths)
+      paths.each do |path|
+        YARD.parse path
+      end
+
+      # Only keep stuff with @path on it
+      YARD::Registry.all.
+        reject { |r| r.tags(:apidoc).empty? }.
+        map { |t| Endpoint.new(t) }.
+        sort_by { |e| e.path || '' }
+    end
+  end
+
+end

data/lib/yardbird/version.rb

@@ -0,0 +1,3 @@
+module Yardbird
+  VERSION = "0.0.2"
+end

data/lib/yardbird/writer.rb

@@ -0,0 +1,63 @@
+module Yardbird
+  class Writer
+
+    def initialize(stream, options = {})
+      @stream = stream
+      @section_level = options[:section_level] || 0
+      @indent_level = 0
+    end
+
+    def flush
+      @stream.flush
+    end
+
+    def line(*args)
+      if @need_blank
+        @stream.write("\n")
+        @need_blank = false
+      end
+      @stream.write(' ' * @indent_level)
+      @stream.write(args.join)
+      @stream.write("\n")
+    end
+
+    def section(title = nil, &block)
+      heading(title) if title
+
+      @section_level += 1
+      yield
+      @section_level -= 1
+    end
+
+    def blank
+      @need_blank = true
+    end
+
+    def heading(s, options = {})
+      if (anchor = options[:anchor])
+        s = "<a name='#{anchor}'>#{s}</a>"
+      end
+
+      blank
+      line(('#' * (@section_level + 1)) + " #{s}")
+      blank
+    end
+
+    def bullet(s)
+      line("* #{s}")
+    end
+
+    def code_block(&block)
+      indent(4) do
+        yield
+      end
+    end
+
+    def indent(count = 1, &block)
+      @indent_level += count
+      yield
+      @indent_level -= count
+    end
+
+  end
+end

data/yardbird.gemspec

@@ -0,0 +1,30 @@
+# coding: utf-8
+
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+
+require 'yardbird/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "yardbird"
+  spec.version       = Yardbird::VERSION
+  spec.authors       = ["Alexander Staubo"]
+  spec.email         = ["alex@bengler.no"]
+  spec.summary       =
+  spec.description   = %q{Yardbird produces REST API documentation from Yardoc comments in Ruby code, via Markdown.}
+  spec.homepage      = ""
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_runtime_dependency 'yard', '~> 0.8'
+  spec.add_runtime_dependency 'yard-sinatra', '~> 1.0'
+  spec.add_runtime_dependency 'mercenary', '~> 0.3'
+  spec.add_runtime_dependency 'activesupport', '~> 4.0'
+
+  spec.add_development_dependency "bundler", "~> 1.6"
+  spec.add_development_dependency "rake"
+end

metadata

@@ -0,0 +1,145 @@
+--- !ruby/object:Gem::Specification
+name: yardbird
+version: !ruby/object:Gem::Version
+  version: 0.0.2
+platform: ruby
+authors:
+- Alexander Staubo
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-05-14 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.8'
+- !ruby/object:Gem::Dependency
+  name: yard-sinatra
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: mercenary
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.3'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '4.0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.6'
+- !ruby/object:Gem::Dependency
+  name: rake
+  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: Yardbird produces REST API documentation from Yardoc comments in Ruby
+  code, via Markdown.
+email:
+- alex@bengler.no
+executables:
+- yardbird
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/yardbird
+- lib/yardbird.rb
+- lib/yardbird/endpoint.rb
+- lib/yardbird/generator.rb
+- lib/yardbird/parser.rb
+- lib/yardbird/version.rb
+- lib/yardbird/writer.rb
+- yardbird.gemspec
+homepage: ''
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.0.3
+signing_key: 
+specification_version: 4
+summary: Yardbird produces REST API documentation from Yardoc comments in Ruby code,
+  via Markdown.
+test_files: []
+has_rdoc: