fdoc 0.2.1

data/lib/fdoc/meta_service.rb

@@ -0,0 +1,46 @@
+require 'yaml'
+
+# MetaServices are collections of services
+class Fdoc::MetaService
+  attr_reader :meta_service_dir
+
+  def initialize(meta_service_dir)
+    @meta_service_dir = meta_service_dir
+
+    service_path = Dir["#{meta_service_dir}/*.fdoc.meta"].first
+    @schema = if service_path
+      YAML.load_file(service_path)
+    else
+      {}
+    end
+  end
+
+  def empty?
+    @schema.empty?
+  end
+
+  def services
+    @schema['services'].map do |path|
+      service_path = if path.start_with?('/') || path.start_with?('~')
+        path
+      else
+        File.join(meta_service_dir, path)
+      end
+      serv = Fdoc::Service.new(service_path)
+      serv.meta_service = self
+      serv
+    end
+  end
+
+  def name
+    @schema['name']
+  end
+
+  def description
+    @schema['description']
+  end
+
+  def discussion
+    @schema['discussion']
+  end
+end

data/lib/fdoc/presenters/endpoint_presenter.rb

@@ -0,0 +1,152 @@
+# HtmlPresenter for an Endpoint
+class Fdoc::EndpointPresenter < Fdoc::HtmlPresenter
+  attr_accessor :service_presenter, :endpoint
+
+  def initialize(endpoint, options = {})
+    super(options)
+    @endpoint = endpoint
+  end
+
+  def to_html
+    render_erb('endpoint.html.erb')
+  end
+
+  def name
+    <<-EOS
+    <span class="endpoint-name #{@endpoint.deprecated? ? 'deprecated' : nil}">
+      <span class="verb">#{@endpoint.verb}</span>
+      <span class="root">#{zws_ify(@endpoint.service.base_path)}</span><span
+       class="path">#{zws_ify(@endpoint.path)}</span>
+      #{@endpoint.deprecated? ? '(deprecated)' : nil}
+    </span>
+    EOS
+  end
+
+  def name_as_link
+    <<-EOS
+    <a href="#{url}">
+      #{name}
+    </a>
+    EOS
+  end
+
+  def url(extension = ".html")
+    '%s%s-%s%s' % [ options[:prefix], endpoint.path, endpoint.verb, extension ]
+  end
+
+  def title
+    '%s %s - %s' % [ endpoint.verb, endpoint.path, endpoint.service.name ]
+  end
+
+  def prefix
+    endpoint.path.split("/").first
+  end
+
+  def zws_ify(str)
+    # zero-width-space, makes long lines friendlier for breaking
+    str.gsub(/\//, '&#8203;/') if str
+  end
+
+  def description
+    render_markdown(endpoint.description)
+  end
+
+  def show_request?
+    !endpoint.request_parameters.empty?
+  end
+
+  def show_response?
+    !endpoint.response_parameters.empty?
+  end
+
+  def request_parameters
+    Fdoc::SchemaPresenter.new(endpoint.request_parameters,
+      options.merge(:request => true)
+    ).to_html
+  end
+
+  def response_parameters
+    Fdoc::SchemaPresenter.new(endpoint.response_parameters, options).to_html
+  end
+
+  def response_codes
+    @response_codes ||= endpoint.response_codes.map do |response_code|
+      Fdoc::ResponseCodePresenter.new(response_code, options)
+    end
+  end
+
+  def successful_response_codes
+    response_codes.select { |response_code| response_code.successful? }
+  end
+
+  def failure_response_codes
+    response_codes.select { |response_code| !response_code.successful? }
+  end
+
+  def example_request
+    render_json(example_from_schema(endpoint.request_parameters))
+  end
+
+  def example_response
+    render_json(example_from_schema(endpoint.response_parameters))
+  end
+
+  ATOMIC_TYPES = %w(string integer number boolean null)
+
+  def example_from_schema(schema)
+    if schema.nil?
+      return nil
+    end
+
+    type = Array(schema["type"])
+
+    if type.any? { |t| ATOMIC_TYPES.include?(t) }
+      schema["example"] || schema["default"] || example_from_atom(schema)
+    elsif type.include?("object") || schema["properties"]
+      example_from_object(schema)
+    elsif type.include?("array") || schema["items"]
+      example_from_array(schema)
+    else
+      {}
+    end
+  end
+
+  def example_from_atom(schema)
+    type = Array(schema["type"])
+    hash = schema.hash
+
+    if type.include?("boolean")
+      [true, false][hash % 2]
+    elsif type.include?("integer")
+      hash % 1000
+    elsif type.include?("number")
+      Math.sqrt(hash % 1000).round 2
+    elsif type.include?("string")
+      ""
+    else
+      nil
+    end
+  end
+
+  def example_from_object(object)
+    example = {}
+    if object["properties"]
+      object["properties"].each do |key, value|
+        example[key] = example_from_schema(value)
+      end
+    end
+    example
+  end
+
+  def example_from_array(array)
+    if array["items"].kind_of? Array
+      example = []
+      array["items"].each do |item|
+        example << example_from_schema(item)
+      end
+      example
+    else
+      [ example_from_schema(array["items"]) ]
+    end
+  end
+end

data/lib/fdoc/presenters/html_presenter.rb

@@ -0,0 +1,58 @@
+require 'erb'
+require 'kramdown'
+
+# HtmlPresenters assist in generating Html for fdoc classes.
+# HtmlPresenters is an abstract class with a lot of helper methods
+# for URLs and common text styling tasks (like #render_markdown
+# and #render_json)
+class Fdoc::HtmlPresenter
+  attr_reader :options
+
+  def initialize(options = {})
+    @options = options
+  end
+
+  def render_erb(erb_name)
+    template_path = File.join(File.dirname(__FILE__), "../templates", erb_name)
+    template = ERB.new(File.read(template_path))
+    template.result(binding)
+  end
+
+  def render_markdown(markdown_str)
+    if markdown_str
+      Kramdown::Document.new(markdown_str, :entity_output => :numeric).to_html
+    else
+      nil
+    end
+  end
+
+  def render_json(json)
+    if json.kind_of? String
+      '<tt>&quot;%s&quot;</tt>' % json.gsub(/\"/, 'quot;')
+    elsif json.kind_of?(Numeric) ||
+          json.kind_of?(TrueClass) ||
+          json.kind_of?(FalseClass)
+      '<tt>%s</tt>' % json
+    elsif json.kind_of?(Hash) ||
+          json.kind_of?(Array)
+      '<pre><code>%s</code></pre>' % JSON.pretty_generate(json)
+    end
+  end
+
+  def html_directory
+    options[:url_base_path] || options[:html_directory] || ""
+  end
+
+  def css_path
+    File.join(html_directory, "styles.css")
+  end
+
+  def index_path(subdirectory = "")
+    html_path = File.join(html_directory, subdirectory)
+    if options[:static_html]
+      File.join(html_path, 'index.html')
+    else
+      html_path
+    end
+  end
+end

data/lib/fdoc/presenters/meta_service_presenter.rb

@@ -0,0 +1,65 @@
+# HtmlPresenter for Fdoc::MetaService
+class Fdoc::MetaServicePresenter < Fdoc::HtmlPresenter
+  attr_reader :meta_service
+
+  def initialize(meta_service, options = {})
+    super(options)
+    @meta_service = meta_service
+  end
+
+  def to_html
+    render_erb('meta_service.html.erb')
+  end
+
+  def services
+    @services ||= meta_service.services.
+      sort_by(&:name).
+      map do |service|
+        Fdoc::ServicePresenter.new(service, options)
+      end
+  end
+
+  def endpoints
+    if !@endpoints
+      @endpoints = []
+      prefix = nil
+
+      ungrouped_endpoints.each do |endpoint|
+        presenter = presenter_from_endpoint(endpoint)
+        current_prefix = presenter.prefix
+
+        @endpoints << [] if prefix != current_prefix
+        @endpoints.last << presenter
+
+        prefix = current_prefix
+      end
+    end
+
+    @endpoints
+  end
+
+  def description
+    render_markdown(meta_service.description)
+  end
+
+  def discussion
+    render_markdown(meta_service.discussion)
+  end
+
+  private
+
+  def ungrouped_endpoints
+    meta_service.services.
+                 map(&:endpoints).
+                 flatten.
+                 sort_by(&:endpoint_path)
+  end
+
+  def presenter_from_endpoint(endpoint)
+    service_presenter = Fdoc::ServicePresenter.new(endpoint.service)
+
+    presenter = Fdoc::EndpointPresenter.new(endpoint,
+      options.merge(:prefix => (service_presenter.slug_name + "/")))
+    presenter.service_presenter = service_presenter
+  end
+end

data/lib/fdoc/presenters/response_code_presenter.rb

@@ -0,0 +1,32 @@
+# An HtmlPresenter for ResponseCodes
+class Fdoc::ResponseCodePresenter < Fdoc::HtmlPresenter
+  attr_reader :response_code
+
+  def initialize(response_code, options)
+    super(options)
+    @response_code = response_code
+  end
+
+  def to_html
+    <<-EOS
+      <div class="response-code">
+        <span class="status">
+          #{status}
+        </span>
+        #{description}
+      </div>
+    EOS
+  end
+
+  def successful?
+    response_code["successful"]
+  end
+
+  def status
+    response_code["status"]
+  end
+
+  def description
+    render_markdown(response_code["description"])
+  end
+end

data/lib/fdoc/presenters/schema_presenter.rb

@@ -0,0 +1,138 @@
+# An HtmlPresenter for a JSON Schema fragment. Like most JSON
+# schema things, has a tendency to recurse.
+class Fdoc::SchemaPresenter < Fdoc::HtmlPresenter
+  FORMATTED_KEYS = %w(
+    description
+    type
+    required
+    example
+    deprecated
+    default
+    format
+    enum
+    items
+    properties
+  )
+
+  def initialize(schema, options)
+    super(options)
+    @schema = schema
+  end
+
+  def request?
+    options[:request]
+  end
+
+  def nested?
+    options[:nested]
+  end
+
+  def to_html
+    html = StringIO.new
+
+    html << '<span class="deprecated">Deprecated</span>' if deprecated?
+
+    html << '<div class="schema">'
+    html << render_markdown(@schema["description"])
+
+    html << '<ul>'
+    begin
+      html << '<li>Type: %s</li>' % type if type
+      html << '<li>Format: %s</li>' % format if format
+      html << '<li>Required: %s</li>' % required? if nested?
+      html << '<li>Example: %s</li>' % example if example
+      html << enum_html
+
+      (@schema.keys - FORMATTED_KEYS).each do |key|
+        html << '<li>%s: %s</li>' % [ key, @schema[key] ]
+      end
+
+      html << items_html
+      html << properties_html
+    end
+
+
+    html << '</ul>'
+    html << '</div>'
+
+    html.string
+  end
+
+  def type
+    t = @schema["type"]
+    if t.kind_of? Array
+      t.join(", ")
+    elsif t != "object"
+      t
+    end
+  end
+
+  def format
+    @schema["format"]
+  end
+
+  def example
+    return unless e = @schema["example"]
+
+    render_json(e)
+  end
+
+  def deprecated?
+    @schema["deprecated"]
+  end
+
+  def required?
+    @schema["required"] ? "yes" : "no"
+  end
+
+  def enum_html
+    enum = @schema["enum"]
+    return unless enum
+
+    list = enum.map do |e|
+      '<tt>%s</tt>' % e
+    end.join(", ")
+
+    html = StringIO.new
+    html << '<li>Enum: '
+    html << list
+    html << '</li>'
+    html.string
+  end
+
+  def items_html
+    return unless items = @schema["items"]
+
+    html = ""
+    html << '<li>Items'
+
+    sub_options = options.merge(:nested => true)
+
+    if items.kind_of? Array
+      item.compact.each do |item|
+        html << self.class.new(item, sub_options).to_html
+      end
+    else
+      html << self.class.new(items, sub_options).to_html
+    end
+
+    html << '</li>'
+    html
+  end
+
+  def properties_html
+    return unless properties = @schema["properties"]
+
+    html = ""
+
+    properties.each do |key, property|
+      next if property.nil?
+      html << '<li>'
+      html << '<tt>%s</tt>' % key
+      html << self.class.new(property, options.merge(:nested => true)).to_html
+      html << '</li>'
+    end
+
+    html
+  end
+end