fdoc 0.3.0 → 0.3.1

data/README.md

@@ -24,6 +24,12 @@ Tell fdoc where to look for `.fdoc` files. By default, fdoc will look in `docs/f
 require 'fdoc'
 
 Fdoc.service_path = "path/to/your/fdocs"
+
+# Configure how Fdoc decides a successful response
+Fdoc.decide_success_with do |response, status|
+ status.to_i < 400
+end
+
 ```
 
 fdoc is built to work around controller specs in rspec, and provides `Fdoc::SpecWatcher` as a mixin. Make sure to include it *inside* your top level describe.
@@ -88,6 +94,15 @@ In this repo, try running:
 
     bin/fdoc convert ./spec/fixtures --output=./html
 
+```
+Options:
+  -o, [--output=OUTPUT]                # Output path
+  -u, [--url-base-path=URL_BASE_PATH]  # URL base path
+  -f, [--format=FORMAT]                # Format in html or markdown, defaults to html
+                                       # Default: html
+  -t, [--templates=TEMPLATES]          # Directory with override templates
+```
+
 ## Example
 
 `.fdoc` files are YAML files based on [JSON schema][json_schema] to describe API endpoints. They derive their endpoint path and verb from their filename.

data/lib/fdoc.rb

@@ -38,7 +38,8 @@ require 'fdoc/service'
 require 'fdoc/meta_service'
 require 'fdoc/endpoint'
 require 'fdoc/endpoint_scaffold'
-require 'fdoc/presenters/html_presenter'
+require 'fdoc/presenters/json_presenter'
+require 'fdoc/presenters/base_presenter'
 require 'fdoc/presenters/service_presenter'
 require 'fdoc/presenters/meta_service_presenter'
 require 'fdoc/presenters/endpoint_presenter'

data/lib/fdoc/cli.rb

@@ -19,11 +19,13 @@ module Fdoc
       File.expand_path("../templates", __FILE__)
     end
 
-    desc "convert FDOC_PATH", "Convert fdoc to HTML"
-    method_option :output, :aliases => "-o", :desc => "HTML output path"
+    desc "convert FDOC_PATH", "Convert fdoc to HTML or Markdowns"
+    method_option :output, :aliases => "-o", :desc => "Output path"
     method_option :url_base_path, :aliases => "-u", :desc => "URL base path"
+    method_option :format, :aliases => "-f", :desc => "Format in html or markdown, defaults to html", :default => "html"
+    method_option :templates, :aliases => "-t", :desc => "Template overrides path"
     def convert(fdoc_path)
-      say_status nil, "Converting fdoc to HTML"
+      say_status nil, "Converting fdoc to #{options[:format]}"
 
       self.origin_path = File.expand_path(fdoc_path)
       raise Fdoc::NotFound.new(origin_path) unless has_valid_origin?
@@ -33,25 +35,51 @@ module Fdoc
       raise Fdoc::NotADirectory.new(output_path) unless has_valid_destination?
       say_status :inside, output_path
 
-      in_root do
-        copy_file("styles.css")
-        create_file("index.html", meta_presenter.to_html) if has_meta_service?
+      if options[:format] == 'markdown'
+        convert_to_markdown
+      else
+        convert_to_html
       end
+    end
 
-      service_presenters.each do |service_presenter|
-        inside_service_presenter(service_presenter) do
-          create_file("index.html", service_presenter.to_html)
+    no_tasks do
+      def convert_to_html
+        in_root do
+          copy_file("styles.css")
+          create_file("index.html", meta_presenter.to_html) if has_meta_service?
+        end
 
-          service_presenter.endpoints.each do |endpoint_prefix_group|
-            endpoint_prefix_group.each do |endpoint|
-              create_file(endpoint.url, endpoint.to_html)
+        service_presenters.each do |service_presenter|
+          inside_service_presenter(service_presenter) do
+            create_file("index.html", service_presenter.to_html)
+
+            service_presenter.endpoints.each do |endpoint_prefix_group|
+              endpoint_prefix_group.each do |endpoint|
+                create_file(endpoint.url, endpoint.to_html)
+              end
+            end
+          end
+        end
+      end
+
+      def convert_to_markdown
+        in_root do
+          create_file("index.md", meta_presenter.to_markdown) if has_meta_service?
+        end
+
+        service_presenters.each do |service_presenter|
+          inside_service_presenter(service_presenter) do
+            create_file("index.md", service_presenter.to_markdown)
+
+            service_presenter.endpoints.each do |endpoint_prefix_group|
+              endpoint_prefix_group.each do |endpoint|
+                create_file(endpoint.url('.md'), endpoint.to_markdown)
+              end
             end
           end
         end
       end
-    end
 
-    no_tasks do
       def inside_service_presenter(service, &block)
         if has_meta_service?
           inside(service.slug_name, {:verbose => true}, &block)
@@ -65,7 +93,16 @@ module Fdoc
           if options[:output]
             File.expand_path(options[:output])
           else
-            File.expand_path("../html", origin_path)
+            File.expand_path("../#{options[:format]}", origin_path)
+          end
+      end
+
+      def template_path
+        @template_path ||=
+          if options[:templates]
+            File.expand_path(options[:templates])
+          else
+            File.expand_path("../templates", origin_path)
           end
       end
 
@@ -91,6 +128,7 @@ module Fdoc
         {
           :static_html => true,
           :url_base_path => options[:url_base_path],
+          :template_directory => template_path,
           :html_directory => destination_root
         }
       end

data/lib/fdoc/meta_service.rb

@@ -5,7 +5,7 @@ class Fdoc::MetaService
   attr_reader :meta_service_dir
 
   def initialize(meta_service_dir)
-    @meta_service_dir = meta_service_dir
+    @meta_service_dir = File.expand_path(meta_service_dir)
 
     service_path = Dir["#{meta_service_dir}/*.fdoc.meta"].first
     @schema = if service_path

data/lib/fdoc/presenters/{html_presenter.rb → base_presenter.rb}

@@ -1,21 +1,25 @@
 require 'erb'
 require 'kramdown'
 require 'json'
+require 'forwardable'
 
-# HtmlPresenters assist in generating Html for fdoc classes.
-# HtmlPresenters is an abstract class with a lot of helper methods
+# BasePresenters assist in generating Html for fdoc classes.
+# BasePresenters 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
+class Fdoc::BasePresenter
   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))
+  def render_erb(erb_name, binding = get_binding)
+    template_path = File.join(options[:template_directory], erb_name)
+    if !File.exists? template_path
+      template_path = File.join(File.dirname(__FILE__), "../templates", erb_name)
+    end
+    template = ERB.new(File.read(template_path), nil, '-')
     template.result(binding)
   end
 
@@ -27,17 +31,8 @@ class Fdoc::HtmlPresenter
     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
+  def get_binding
+    binding
   end
 
   def html_directory

data/lib/fdoc/presenters/endpoint_presenter.rb

@@ -1,33 +1,19 @@
-# HtmlPresenter for an Endpoint
-class Fdoc::EndpointPresenter < Fdoc::HtmlPresenter
-  attr_accessor :service_presenter, :endpoint
+# BasePresenter for an Endpoint
+class Fdoc::EndpointPresenter < Fdoc::BasePresenter
+  attr_accessor :service_presenter, :endpoint, :endpoint_presenter
 
   def initialize(endpoint, options = {})
     super(options)
     @endpoint = endpoint
+    @endpoint_presenter = self
   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
+  def to_markdown
+    render_erb('endpoint.md.erb')
   end
 
   def url(extension = ".html")
@@ -62,11 +48,11 @@ class Fdoc::EndpointPresenter < Fdoc::HtmlPresenter
   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
+    Fdoc::SchemaPresenter.new(endpoint.response_parameters, options)
   end
 
   def response_codes
@@ -84,11 +70,23 @@ class Fdoc::EndpointPresenter < Fdoc::HtmlPresenter
   end
 
   def example_request
-    render_json(example_from_schema(endpoint.request_parameters))
+    Fdoc::JsonPresenter.new(example_from_schema(endpoint.request_parameters))
   end
 
   def example_response
-    render_json(example_from_schema(endpoint.response_parameters))
+    Fdoc::JsonPresenter.new(example_from_schema(endpoint.response_parameters))
+  end
+
+  def deprecated?
+    @endpoint.deprecated?
+  end
+
+  def base_path
+    zws_ify(@endpoint.service.base_path)
+  end
+
+  def path
+    zws_ify(@endpoint.path)
   end
 
   ATOMIC_TYPES = %w(string integer number boolean null)

data/lib/fdoc/presenters/json_presenter.rb

@@ -0,0 +1,31 @@
+require 'erb'
+require 'json'
+class Fdoc::JsonPresenter
+  attr_reader :json
+
+  def initialize(json)
+    @json = json
+  end
+
+  def to_html
+    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 to_markdown
+    if json.kind_of?(Hash) ||
+       json.kind_of?(Array)
+      JSON.pretty_generate(json)
+    else
+      json
+    end
+  end
+end

data/lib/fdoc/presenters/meta_service_presenter.rb

@@ -1,16 +1,27 @@
-# HtmlPresenter for Fdoc::MetaService
-class Fdoc::MetaServicePresenter < Fdoc::HtmlPresenter
+# BasePresenter for Fdoc::MetaService
+class Fdoc::MetaServicePresenter < Fdoc::BasePresenter
   attr_reader :meta_service
+  extend Forwardable
+
+  def_delegators :meta_service, :name, :meta_service_dir
 
   def initialize(meta_service, options = {})
     super(options)
     @meta_service = meta_service
   end
 
+  def name
+    meta_service.name
+  end
+
   def to_html
     render_erb('meta_service.html.erb')
   end
 
+  def to_markdown
+    render_erb('meta_service.md.erb')
+  end
+
   def services
     @services ||= meta_service.services.
       sort_by(&:name).
@@ -38,12 +49,20 @@ class Fdoc::MetaServicePresenter < Fdoc::HtmlPresenter
     @endpoints
   end
 
-  def description
-    render_markdown(meta_service.description)
+  def description(options = {:render => true})
+    options[:render] ? render_markdown(meta_service.description) : meta_service.description
+  end
+
+  def discussion(options = {:render => true})
+    options[:render] ? render_markdown(meta_service.discussion) : meta_service.discussion
   end
 
-  def discussion
-    render_markdown(meta_service.discussion)
+  def relative_service_path(service_presenter, file_name = nil)
+    service_path = service_presenter.slug_name
+    if file_name
+      service_path = File.join(service_path, file_name)
+    end
+    service_path
   end
 
   private

data/lib/fdoc/presenters/response_code_presenter.rb

@@ -1,5 +1,5 @@
-# An HtmlPresenter for ResponseCodes
-class Fdoc::ResponseCodePresenter < Fdoc::HtmlPresenter
+# An BasePresenter for ResponseCodes
+class Fdoc::ResponseCodePresenter < Fdoc::BasePresenter
   attr_reader :response_code
 
   def initialize(response_code, options)
@@ -18,6 +18,10 @@ class Fdoc::ResponseCodePresenter < Fdoc::HtmlPresenter
     EOS
   end
 
+  def to_markdown
+    "__#{status}__: #{description_raw}"
+  end
+
   def successful?
     response_code["successful"]
   end
@@ -27,6 +31,11 @@ class Fdoc::ResponseCodePresenter < Fdoc::HtmlPresenter
   end
 
   def description
-    render_markdown(response_code["description"])
+    render_markdown(description_raw)
   end
-end
+
+  def description_raw
+    response_code["description"]
+  end
+
+end

data/lib/fdoc/presenters/schema_presenter.rb

@@ -1,6 +1,6 @@
-# An HtmlPresenter for a JSON Schema fragment. Like most JSON
+# An BasePresenter for a JSON Schema fragment. Like most JSON
 # schema things, has a tendency to recurse.
-class Fdoc::SchemaPresenter < Fdoc::HtmlPresenter
+class Fdoc::SchemaPresenter < Fdoc::BasePresenter
   FORMATTED_KEYS = %w(
     description
     type
@@ -40,7 +40,7 @@ class Fdoc::SchemaPresenter < Fdoc::HtmlPresenter
       html << '<li>Required: %s</li>' % required? if nested?
       html << '<li>Type: %s</li>' % type if type
       html << '<li>Format: %s</li>' % format if format
-      html << '<li>Example: %s</li>' % example if example
+      html << '<li>Example: %s</li>' % example.to_html if example
       html << enum_html
 
       (@schema.keys - FORMATTED_KEYS).each do |key|
@@ -58,6 +58,38 @@ class Fdoc::SchemaPresenter < Fdoc::HtmlPresenter
     html.string
   end
 
+  def to_markdown(prefix = "")
+    md = StringIO.new
+    md << 'Deprecated' if deprecated?
+    md << "\n#{@schema["description"]}"
+    md << "\n#{prefix}* __Required__: #{required?}" if nested?
+    md << "\n#{prefix}* __Type__: #{type}" if type
+    md << "\n#{prefix}* __Format__: #{format}" if format
+    md << "\n#{prefix}* __Example__: <tt>#{example.to_markdown}</tt>" if example
+    md << "\n#{@schema['enum']}"
+    (@schema.keys - Fdoc::SchemaPresenter::FORMATTED_KEYS).each do |key|
+      md << "\n#{prefix}* %{key} %{@schema[key]}"
+    end
+    if items = @schema["items"]
+      md << "\n#{prefix}* Items"
+      if items.kind_of? Array
+        item.compact.each do |item|
+          md << Fdoc::SchemaPresenter.new(item, options.merge(:nested => true)).to_markdown(prefix + "\t")
+        end
+      else
+        md << Fdoc::SchemaPresenter.new(@schema["items"], options.merge(:nested => true)).to_markdown(prefix + "\t")
+      end
+    end
+    if properties = @schema["properties"]
+      properties.each do |key, property|
+        next if property.nil?
+        md << "\n#{prefix}* __#{key}__:"
+        md << Fdoc::SchemaPresenter.new(property, options.merge(:nested => true)).to_markdown(prefix + "\t")
+      end
+    end
+    md.string
+  end
+
   def type
     t = @schema["type"]
     if t.kind_of? Array
@@ -82,7 +114,7 @@ class Fdoc::SchemaPresenter < Fdoc::HtmlPresenter
   def example
     return unless e = @schema["example"]
 
-    render_json(e)
+    Fdoc::JsonPresenter.new(e)
   end
 
   def deprecated?