fdoc 0.3.0 → 0.3.1

data/lib/fdoc/presenters/service_presenter.rb

@@ -1,7 +1,12 @@
-# An HtmlPresenter for Fdoc::Service
-class Fdoc::ServicePresenter < Fdoc::HtmlPresenter
+# An BasePresenter for Fdoc::Service
+class Fdoc::ServicePresenter < Fdoc::BasePresenter
   attr_reader :service
 
+  extend Forwardable
+
+  def_delegators :service, :name, :service_dir, :meta_service
+
+
   def initialize(service, options = {})
     super(options)
     @service = service
@@ -11,6 +16,10 @@ class Fdoc::ServicePresenter < Fdoc::HtmlPresenter
     render_erb('service.html.erb')
   end
 
+  def to_markdown
+    render_erb('service.md.erb')
+  end
+
   def name_as_link(options = {})
     path = service.meta_service ? index_path(slug_name) : index_path
     '<a href="%s">%s %s</a>' % [ path, options[:prefix], service.name ]
@@ -46,11 +55,21 @@ class Fdoc::ServicePresenter < Fdoc::HtmlPresenter
     @endpoints
   end
 
-  def description
-    render_markdown(service.description)
+  def description(options = {:render => true})
+    options[:render] ? render_markdown(service.description) : service.description
   end
 
-  def discussion
-    render_markdown(service.discussion)
+  def discussion(options = {:render => true})
+    options[:render] ? render_markdown(service.discussion) : service.discussion
   end
+
+  def relative_meta_service_path(file_name = nil)
+    service_path = service_dir.gsub(meta_service.meta_service_dir, "")
+    service_path = service_path.count("/").times.map { "../" }.join
+    if file_name
+      service_path = File.join(service_path, file_name)
+    end
+    service_path
+  end
+
 end

data/lib/fdoc/templates/endpoint.html.erb

@@ -11,7 +11,7 @@
     <div id="page">
       <div id="content">
         <h1>
-          <%= name %>
+          <%= render_erb('shared/endpoint_name.html.erb', endpoint_presenter.get_binding)  %>
         </h1>
 
         <div id="nav">
@@ -31,19 +31,19 @@
           <%= tag_with_anchor('h2', 'Request') %>
 
           <%= tag_with_anchor('h3', 'Example Request') %>
-          <%= example_request %>
+          <%= example_request.to_html %>
 
           <%= tag_with_anchor('h3', 'Request Parameters') %>
-          <%= request_parameters %>
+          <%= request_parameters.to_html %>
         <% end %>
 
         <%= tag_with_anchor('h2', 'Response') %>
         <% if show_response? %>
           <%= tag_with_anchor('h3', 'Example Response') %>
-          <%= example_response %>
+          <%= example_response.to_html %>
 
           <%= tag_with_anchor('h3', 'Response Parameters') %>
-          <%= response_parameters %>
+          <%= response_parameters.to_html %>
         <% end %>
 
         <%= tag_with_anchor('h3', 'Response Codes') %>

data/lib/fdoc/templates/endpoint.md.erb

@@ -0,0 +1,40 @@
+# <%= endpoint.verb -%> <%= base_path -%><%= path -%><%= "deprecated" if deprecated? -%>
+
+<%= description %>
+
+<% if show_request? %>
+## Request
+### Example Request
+```
+<%= example_request.to_markdown %>
+```
+
+### Example Parameters
+<%= request_parameters.to_markdown %>
+<% end %>
+
+## Response
+<% if show_response? %>
+### Example Response
+```
+<%= example_response.to_markdown %>
+```
+
+### Response Parameters
+<%= response_parameters.to_markdown %>
+<% end %>
+
+### Response Codes
+<% if !successful_response_codes.empty? %>
+#### Successful Response Codes
+<% successful_response_codes.each do |response_code| %>
+* <%= response_code.to_markdown %>
+<% end %>
+<% end %>
+
+<% if !successful_response_codes.empty? %>
+#### Failure Response Codes
+<% failure_response_codes.each do |response_code| %>
+* <%= response_code.to_markdown %>
+<% end %>
+<% end %>

data/lib/fdoc/templates/meta_service.html.erb

@@ -35,7 +35,9 @@
           <ul>
           <% endpoint_ary.each do |endpoint| %>
             <li>
-              <%= endpoint.name_as_link %>
+              <a href="<%= endpoint.url %>">
+                <%= render_erb("shared/endpoint_name.html.erb", endpoint.get_binding) %>
+              </a>
             </li>
           <% end %>
           </ul>

data/lib/fdoc/templates/meta_service.md.erb

@@ -0,0 +1,20 @@
+# <%= name %>
+
+<%= description(:render => false) %>
+
+<% services.each do |serv| %>
+  * <%= "[#{serv.name}](#{relative_service_path(serv, "index.md")})" %>
+<% end %>
+
+## Endpoints
+<% endpoints.each do |endpoint_ary| %>
+### <%= endpoint_ary.first.prefix %>
+<% endpoint_ary.each do |endpoint| %>
+* <%= render_erb("shared/endpoint_name.md.erb", endpoint.get_binding) %>
+<% end -%>
+<% end -%>
+
+<% if discussion %>
+## Discussion
+<%= discussion(:render => false) %>
+<% end %>

data/lib/fdoc/templates/service.html.erb

@@ -31,8 +31,10 @@
           <ul>
           <% endpoint_ary.each do |endpoint| %>
             <li>
-              <%= endpoint.name_as_link %>
-            </li>          
+              <a href="<%= endpoint.url %>">
+                <%= render_erb("shared/endpoint_name.html.erb", endpoint.get_binding) %>
+              </a>
+            </li>
           <% end %>
           </ul>
         <% end %>

data/lib/fdoc/templates/service.md.erb

@@ -0,0 +1,18 @@
+# <%= name %>
+<% if meta_service %>
+### &#187; <%= "[#{meta_service.name}](#{relative_meta_service_path("index.md")})" %>
+<% end %>
+
+<%= description(:render => false) %>
+
+<% endpoints.each do |endpoint_ary| %>
+### <%= endpoint_ary.first.prefix %>
+  <% endpoint_ary.each do |endpoint| %>
+  * <%= render_erb("shared/endpoint_name.md.erb", endpoint.get_binding) %>
+  <% end %>
+<% end %>
+
+<% if discussion %>
+## Discussion
+<%= discussion(:render => false) %>
+<% end %>

data/lib/fdoc/templates/shared/endpoint_name.html.erb

@@ -0,0 +1,8 @@
+<span class="endpoint-name <%= 'deprecated' if deprecated? -%>">
+  <span class="verb"><%= endpoint.verb %></span>
+  <span class="root"><%= base_path %></span>
+  <span class="path"><%= path %></span>
+  <% if deprecated? %>
+  (deprecated)
+  <% end %>
+</span>

data/lib/fdoc/templates/shared/endpoint_name.md.erb

@@ -0,0 +1 @@
+<%= endpoint.verb -%> [<%= base_path -%><%= path -%><%= "deprecated" if deprecated? -%>](<%= url('.md') %>)

data/lib/fdoc/templates/styles.css

@@ -61,7 +61,7 @@ tt, kbd, code {
   background: #eee;
   padding: .1em;
   border: 1pt solid #ddd;
-  white-space: pre-wrap;    
+  white-space: pre-wrap;
 }
 
 .endpoint-name {}

data/spec/fdoc/cli_spec.rb

@@ -5,9 +5,10 @@ describe Fdoc::Cli do
   let(:temporary_path) { Dir.mktmpdir("fdoc-cli") }
   let(:fdoc_path) { File.expand_path("fdoc", temporary_path) }
   let(:html_path) { File.expand_path("html", temporary_path) }
-  let(:options) { {} }
+  let(:markdown_path) { File.expand_path("markdown", temporary_path) }
+  let(:options) { { :format => 'html' } }
 
-  subject(:cli) { Fdoc::Cli.new([fdoc_path], options) }
+  subject { Fdoc::Cli.new([fdoc_path], options) }
 
   before { FileUtils.mkdir_p(fdoc_path) }
 
@@ -28,7 +29,7 @@ describe Fdoc::Cli do
 
       it "raises an exception" do
         expect do
-          cli.convert(fdoc_path)
+          subject.convert(fdoc_path)
         end.to raise_exception(Fdoc::NotFound)
       end
     end
@@ -37,7 +38,7 @@ describe Fdoc::Cli do
       context "when the destination does not exist" do
         it "makes a destination directory" do
           expect do
-            cli.convert(fdoc_path)
+            subject.convert(fdoc_path)
           end.to change { File.directory?(html_path) }.to(true)
         end
       end
@@ -47,70 +48,58 @@ describe Fdoc::Cli do
 
         it "raises an exception" do
           expect do
-            cli.convert(fdoc_path)
+            subject.convert(fdoc_path)
           end.to raise_exception(Fdoc::NotADirectory)
         end
       end
 
       it "copies the css to the destination" do
         expect do
-          cli.convert(fdoc_path)
+          subject.convert(fdoc_path)
         end.to change { File.exist?(styles_css_path) }.from(false)
       end
 
-      context "when there is a meta service fdoc" do
-        let(:root_html) { File.expand_path("index.html", html_path) }
-        let(:members_html) do
-          File.expand_path("members_api/index.html", html_path)
-        end
-        let(:endpoint_html) do
-          File.expand_path("members_api/add-PUT.html", html_path)
-        end
-
+      shared_examples "when there is a meta service fdoc" do
         before { with_fixture("sample_group.fdoc.meta") }
 
         context "when no service fdoc exists" do
-          specify { expect { cli.convert(fdoc_path) }.to raise_error }
+          specify { expect { subject.convert(fdoc_path) }.to raise_error }
         end
 
         context "when a service fdoc exists" do
           before { with_fixture("members/members.fdoc.service") }
 
-          it "creates a root-level html file" do
+          it "creates a root-level file" do
             expect do
-              cli.convert(fdoc_path)
-            end.to change { File.exist?(root_html) }.from(false)
+              subject.convert(fdoc_path)
+            end.to change { File.exist?(root_file) }.from(false)
           end
 
-          it "writes the service-level html file" do
+          it "writes the service-level file" do
             expect do
-              cli.convert(fdoc_path)
-            end.to change { File.exist?(members_html) }.from(false)
+              subject.convert(fdoc_path)
+            end.to change { File.exist?(members_file) }.from(false)
           end
 
           context "when an endpoint fdoc exists" do
             before { with_fixture("members/add-PUT.fdoc") }
 
-            it "writes the endpoint html file" do
+            it "writes the endpoint file" do
               expect do
-                cli.convert(fdoc_path)
-              end.to change { File.exist?(endpoint_html) }.from(false)
+                subject.convert(fdoc_path)
+              end.to change { File.exist?(endpoint_file) }.from(false)
             end
           end
         end
       end
 
-      context "when there is no meta service fdoc" do
-        let(:root_html) { File.expand_path("index.html", html_path) }
-        let(:endpoint_html) do
-          File.expand_path("add-PUT.html", html_path)
-        end
+      shared_examples "when there is no meta service fdoc" do
 
         context "when no service fdoc exists" do
           it "creates a dummy index" do
             expect do
-              cli.convert(fdoc_path)
-            end.to change { File.exist?(root_html) }.from(false)
+              subject.convert(fdoc_path)
+            end.to change { File.exist?(root_file) }.from(false)
           end
         end
 
@@ -121,8 +110,8 @@ describe Fdoc::Cli do
 
           it "writes the service-level html file" do
             expect do
-              cli.convert(fdoc_path)
-            end.to change { File.exist?(root_html) }.from(false)
+              subject.convert(fdoc_path)
+            end.to change { File.exist?(root_file) }.from(false)
           end
 
           context "when an endpoint fdoc exists" do
@@ -130,12 +119,61 @@ describe Fdoc::Cli do
 
             it "writes the endpoint html file" do
               expect do
-                cli.convert(fdoc_path)
-              end.to change { File.exist?(endpoint_html) }.from(false)
+                subject.convert(fdoc_path)
+              end.to change { File.exist?(endpoint_file) }.from(false)
             end
           end
         end
       end
+
+      context "output HTML" do
+
+        context "when there is no meta service fdoc" do
+          let(:root_file) { File.expand_path("index.html", html_path) }
+          let(:members_file) do
+            File.expand_path("members_api/index.html", html_path)
+          end
+          let(:endpoint_file) do
+            File.expand_path("members_api/add-PUT.html", html_path)
+          end
+
+          it_behaves_like "when there is a meta service fdoc"
+        end
+
+        context "when there is no meta service fdoc" do
+          let(:root_file) { File.expand_path("index.html", html_path) }
+          let(:endpoint_file) do
+            File.expand_path("add-PUT.html", html_path)
+          end
+          it_behaves_like "when there is no meta service fdoc"
+        end
+
+      end
+
+      context "output Markdown" do
+        let(:options) { { :format => 'markdown' } }
+
+        context "when there is no meta service fdoc" do
+          let(:root_file) { File.expand_path("index.md", markdown_path) }
+          let(:members_file) do
+            File.expand_path("members_api/index.md", markdown_path)
+          end
+          let(:endpoint_file) do
+            File.expand_path("members_api/add-PUT.md", markdown_path)
+          end
+
+          it_behaves_like "when there is a meta service fdoc"
+        end
+
+        context "when there is no meta service fdoc" do
+          let(:root_file) { File.expand_path("index.md", markdown_path) }
+          let(:endpoint_file) do
+            File.expand_path("add-PUT.md", markdown_path)
+          end
+          it_behaves_like "when there is no meta service fdoc"
+        end
+      end
+
     end
   end
 
@@ -203,12 +241,21 @@ describe Fdoc::Cli do
 
   describe "#html_options" do
     let(:html_path) { "/a/great/place/to/keep/html"}
+    let(:template_path) { '/a/great/place/to/keep/templates' }
 
-    before { subject.destination_root = html_path }
+    before do
+      subject.origin_path = fdoc_path
+      subject.destination_root = html_path
+    end
 
     its(:html_options) { should include(:static_html => true) }
     its(:html_options) { should include(:html_directory => html_path) }
 
+    context "when a template_directory is provided" do
+      let(:options) { { :format => 'html', :templates => template_path } }
+      its(:html_options) { should include(:template_directory => template_path) }
+    end
+
     context "when url_base_path is not provided" do
       its(:html_options) { should include(:url_base_path => nil) }
     end
@@ -222,7 +269,7 @@ describe Fdoc::Cli do
   end
 
   describe "#inside_service" do
-    let(:presenter) { cli.service_presenters.first }
+    let(:presenter) { subject.service_presenters.first }
 
     before do
       subject.origin_path = fdoc_path
@@ -236,7 +283,7 @@ describe Fdoc::Cli do
       end
 
       it "leaves the output directory" do
-        cli.inside_service_presenter(presenter) do
+        subject.inside_service_presenter(presenter) do
           Dir.pwd.should =~ %r|#{html_path}/members_api$|
         end
       end
@@ -248,7 +295,7 @@ describe Fdoc::Cli do
       end
 
       it "does not leave the output directory" do
-        cli.inside_service_presenter(presenter) do
+        subject.inside_service_presenter(presenter) do
           Dir.pwd.should =~ /#{html_path}$/
         end
       end