apitome 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: dc6b6b1d1b4087e335ccb621c5ca8c6af0c57489
-  data.tar.gz: 7fa8cfffd520e863cc3097b7eb1a0932786a2da4
+  metadata.gz: 5777e4b12519a2ba27eac422bdec40ea98a1da5d
+  data.tar.gz: ce780e371f4fbf097e0bbc18ea4b88f5c07eb900
 SHA512:
-  metadata.gz: f0d39922af9f8b5308923f654f733264f07604afd299a31a77553d4b67452bf2d1a247283b8c4aeab5fca4fe72c113f0c1d51494dab1392a45265b88972ab0b5
-  data.tar.gz: 9024d5502441305b8351119c9b8c97917c405605f0c7db46e1560c60a34c5c2f3913a6bf2fc9ba2f433b18ad3179d941e47cda6787e3d5e135cff542c01c0c3a
+  metadata.gz: dc0a149de4a4381f5e334e6f20c202364659d94dcec9de1d1420954cd7f6153eb3fe8a8ad70a475f12f79e7b8bb721f0935cce34886ec2731a5006bb572d6e6e
+  data.tar.gz: e094aa68ea16756739bbf87bb5b6e35f53bb6920a1f279ca126b788b57dabaf69947be8a81b56e1b47a0319e021c7b29d6111d47f0c2e9a115545622699dc18d

data/README.md

@@ -3,7 +3,7 @@ Apitome
 
 [![Gem Version](https://img.shields.io/gem/v/apitome.svg)](https://rubygems.org/gems/apitome)
 [![Dependency Status](https://gemnasium.com/modeset/apitome.svg)](https://gemnasium.com/modeset/apitome)
-[![Build Status](https://img.shields.io/travis/modeset/apitome.svg)](https://travis-ci.org/modeset/apitome)
+[![Build Status](https://img.shields.io/travis/jejacks0n/apitome.svg)](https://travis-ci.org/jejacks0n/apitome)
 [![Code Climate](https://img.shields.io/codeclimate/github/modeset/apitome.svg)](https://codeclimate.com/github/modeset/apitome)
 [![Test Coverage](https://codeclimate.com/github/modeset/apitome/badges/coverage.svg)](https://codeclimate.com/github/modeset/apitome)
 [![License](http://img.shields.io/badge/license-MIT-brightgreen.svg)](http://opensource.org/licenses/MIT)
@@ -49,11 +49,92 @@ You can view your documentation at the default `api/docs` route.
 
 ## Configuration
 
+After installation, your app will have an apitome initializer (app/config/initializers/apitome.rb). You will find the following parameters that can be used to customize apitome. Note: Restart rails after changing any of these parameters.
+
+<dl>
+
+<dt> mount_at </dt><dd>
+  This determines where the Apitome routes will be mounted. Changing this to "/api/documentation" for instance would allow you to browse to http://localhost:3000/api/documentation to see your api documentation. Set to nil and mount it yourself if you need to.<br/>
+
+  <b>default:</b> <code>"/api/docs"</code>
+</dd>
+
+<dt> root </dt><dd>
+  This defaults to Rails.root if left nil. If you're providing documentation for an engine using a dummy application it can be useful to set this to your engines root.. E.g. <code>Application::Engine.root</code><br/>
+
+  <b>default:</b> <code>nil</code>
+</dd>
+
+<dt> doc_path </dt><dd>
+  This is where rspec_api_documentation outputs the JSON files. This is configurable within RAD, and so is configurable here.<br/>
+
+  <b>default:</b> <code>"doc/api"</code>
+</dd>
+
+<dt> parent_controller </dt><dd>
+  Set a parent controller that Apitome::DocsController inherits from. Useful if you want to use a custom `before_action`.<br/>
+
+  <b>default:</b> <code>"ActionController::Base"</code>
+</dd>
+
+<dt> title </dt><dd>
+  The title of the documentation -- If your project has a name, you'll want to put it here.<br/>
+
+  <b>default:</b> <code>"Apitome Documentation"</code>
+</dd>
+
+<dt> layout </dt><dd>
+  The main layout view for all documentation pages. By default this is pretty basic, but you may want to use your own application layout.<br/>
+
+  <b>default:</b> <code>"apitome/application"</code>
+</dd>
+
+<dt> code_theme </dt><dd>
+  We're using [highlight.js](https://github.com/isagalaev/highlight.js) for code highlighting, and it comes with some great themes. You can check [here for themes](http://softwaremaniacs.org/media/soft/highlight/test.html), and enter the theme as lowercase/underscore.<br/>
+
+  <b>default:</b> <code>"default"</code>
+</dd>
+
+<dt> css_override </dt><dd>
+  This allows you to override the css manually. You typically want to require `apitome/application` within the override, but if you want to override it entirely you can do so.<br/>
+
+  <b>default:</b> <code>nil</code>
+</dd>
+
+<dt> js_override </dt><dd>
+  This allows you to override the javascript manually. You typically want to require `apitome/application` within the override, but if you want to override it entirely you can do so.<br/>
+
+  <b>default:</b> <code>nil</code>
+</dd>
+
+<dt> readme </dt><dd>
+  You can provide a "README" style markdown file for the documentation, which is a useful place to include general information. This path is relative to your doc_path configuration.<br/>
+
+  <b>default:</b> <code>"../api.md"</code>
+</dd>
+
+<dt> single_page </dt><dd>
+  Apitome can render the documentation into a single page that uses scrollspy, or it can render the documentation on individual pages on demand. This allows you to specify which one you want, as a single page may impact performance.<br/>
+
+  <b>default:</b> <code>true</code>
+
+<dt> url_formatter </dt><dd>
+  You can specify how urls are formatted using a Proc or other callable object.  Your proc will be called with a resource name or link, giving you the opportunity to modify it as necessary for in the documentation url.<br/>
+
+  <b>default:</b> <code>-> (str) { str.gsub(/\.json$/, '').underscore.gsub(/[^0-9a-z]+/i, '-') }</code>
+</dd>
+
+<dt> precompile_assets </dt><dd>
+  By default all assets that ship with this library are precompiled by the asset pipeline. If you would prefer to control this yourself, you can disable it by changing this to false.<br/>
+
+  <b>default:</b> <code>true</code>
+</dd>
+=======
+
 When you install Apitime an initializer file (app/config/initializers/apitome.rb) is generated that contains good
 documentation for each configuration directive. Otherwise you can get a refresher by checking the
 [Apitome Configuration](https://github.com/modeset/apitome/wiki/Apitome-Configuration) article.
 
-
 ## Customization
 
 You can put custom views and partials in your own `views/apitome/docs` -- check the repo here for

data/app/assets/javascripts/apitome/application.js

@@ -14,3 +14,19 @@ jQuery(function(){
   })
 });
 
+$(document).ready(function() {
+  $(window).scroll(function(){
+    if ($(this).scrollTop() > 1500) {
+      $('#scroll-to-top').removeClass('hidden').affix({
+        offset: { top:100 }
+      });
+    } else {
+      $('#scroll-to-top').addClass('hidden')
+    }
+  });
+  
+  $("#scroll-to-top").click(function(){
+    $('html, body').animate({scrollTop : 0},500);
+    return false;
+  });
+});

data/app/assets/stylesheets/apitome/application.css

@@ -135,3 +135,13 @@ body.single-page .docs-section > section.readme article {
   }
 }
 
+.sidebar {
+  overflow: auto;
+  max-height: 550px;
+}
+
+#scroll-to-top.affix {
+  position: fixed; /* keeps it on the bottom once in view */
+  bottom: 18px;
+  right: 1px;
+}

data/app/controllers/apitome/docs_controller.rb

@@ -1,4 +1,6 @@
-class Apitome::DocsController < ActionController::Base
+require 'open-uri'
+
+class Apitome::DocsController < Object.const_get(Apitome.configuration.parent_controller)
   layout Apitome.configuration.layout
 
   helper_method *[
@@ -22,19 +24,31 @@ class Apitome::DocsController < ActionController::Base
   def simulate
     request = example["requests"][0]
     if request
+      request["response_headers"].delete('Content-Length')
       request["response_headers"].each { |k, v| headers[k] = v }
-      render text: request["response_body"], status: request["response_status"]
+      render body: request["response_body"], status: request["response_status"]
     else
-      render text: "No simulation for this endpoint", status: 404
+      render body: "No simulation for this endpoint", status: 404
     end
   end
 
   private
 
-  def file_for(file)
-    file = Apitome.configuration.root.join(Apitome.configuration.doc_path, file)
-    raise Apitome::FileNotFoundError.new("Unable to find #{file}") unless File.exists?(file)
-    File.read(file)
+  def file_for(file, readme: false)
+    if Apitome.configuration.remote_docs
+      file = if readme
+        "#{file}"
+      else
+        "#{Apitome.configuration.doc_path}/#{file}"
+      end
+
+      file = "#{Apitome.configuration.remote_url}/#{file}"
+    else
+      file = Apitome.configuration.root.join(Apitome.configuration.doc_path, file)
+      raise Apitome::FileNotFoundError.new("Unable to find #{file}") unless File.exists?(file)
+    end
+
+    open(file).read
   end
 
   def resources
@@ -51,8 +65,7 @@ class Apitome::DocsController < ActionController::Base
 
   def formatted_readme
     return unless Apitome.configuration.readme
-    file = Apitome.configuration.root.join(Apitome.configuration.doc_path, Apitome.configuration.readme)
-    rendered_markdown(file_for(file))
+    rendered_markdown(file_for(Apitome.configuration.readme, readme: true))
   end
 
   def rendered_markdown(string)
@@ -87,6 +100,6 @@ class Apitome::DocsController < ActionController::Base
   end
 
   def id_for(str)
-    str.gsub(/\.json$/, "").underscore.gsub(/[^0-9a-z]+/i, "-")
+    Apitome.configuration.url_formatter.call(str)
   end
 end

data/app/helpers/apitome/docs_helper.rb

@@ -0,0 +1,23 @@
+module Apitome::DocsHelper
+  def format_scope(scope)
+    Array(scope).each_with_index.map do |scope, index|
+      if index == 0
+        scope
+      else
+        "[#{scope}]"
+      end
+    end.join
+  end
+
+  def resource_link(resource)
+    "#{Apitome.configuration.mount_at}/#{resource['examples'].first['link'].gsub(/\.json$/, '')}"
+  end
+
+  def example_link(example)
+    "#{Apitome.configuration.mount_at}/#{example['link'].gsub(/\.json$/, '')}"
+  end
+
+  def link_active?(link)
+    current_page?(url_for(link))
+  end
+end

data/app/views/apitome/docs/_all_examples.html.erb

@@ -1,6 +1,9 @@
 <% resources.each do |resource| %>
   <section class="example" id="<%= id_for(resource['name']) %>">
     <h1 class="resource-name"><%= resource['name'] %></h1>
+
+    <%= render partial: 'resource_explanation', locals: { explanation: resource['explanation'] } if resource['explanation'] %>
+
     <% resource['examples'].each do |example| %>
       <% link = example['link'].gsub('.json', '') %>
       <article id="<%= id_for(link) %>">

data/app/views/apitome/docs/_body.html.erb

@@ -1,4 +1,4 @@
 <section class="body">
-  <h4><%= t(:body) %></h4>
+  <h4><%= t(:body, scope: :apitome) %></h4>
   <pre><code class="<%= type %>"><%= formatted_body(body, type) %></code></pre>
 </section>

data/app/views/apitome/docs/_curl.html.erb

@@ -1,4 +1,4 @@
 <section class="curl">
-  <h4><%= t(:curl) %></h4>
+  <h4><%= t(:curl, scope: :apitome) %></h4>
   <pre><%= request['curl'] %></pre>
 </section>

data/app/views/apitome/docs/_endpoint.html.erb

@@ -1,4 +1,4 @@
 <section class="endpoint">
-  <h3><%= t(:endpoint) %></h3>
+  <h3><%= t(:endpoint, scope: :apitome) %></h3>
   <pre><%= "#{method} #{endpoint}" %></pre>
 </section>

data/app/views/apitome/docs/_example.html.erb

@@ -6,7 +6,7 @@
 
 <% example['requests'].each_with_index do |request, index| %>
   <div id="<%= "request-#{index}" %>">
-    <h3><%= t(:request) %></h3>
+    <h3><%= t(:request, scope: :apitome) %></h3>
     <div class="request">
       <%= render partial: 'apitome/docs/route',    locals: {request: request, index: index} %>
       <%= render partial: 'apitome/docs/headers',  locals: {request: request, index: index, headers: request['request_headers']} %>
@@ -15,9 +15,9 @@
       <%= render partial: 'apitome/docs/curl',     locals: {request: request, index: index} if request['curl'] %>
     </div>
 
-    <h3><%= t(:response) %></h3>
+    <h3><%= t(:response, scope: :apitome) %></h3>
     <div class="response">
-      <%= link_to('Simulated Response', "#{Apitome.configuration.mount_at}/simulate/#{link}") %>
+      <%= link_to('Simulated Response', apitome.simulated_path(link)) unless link.empty? %>
       <%= render partial: 'apitome/docs/response_fields', locals: {params: example['response_fields']} if example['response_fields'].size > 0 %>
       <%= render partial: 'apitome/docs/status',          locals: {request: request, index: index} %>
       <%= render partial: 'apitome/docs/headers',         locals: {request: request, index: index, headers: request['response_headers']} %>

data/app/views/apitome/docs/_headers.html.erb

@@ -1,4 +1,6 @@
-<section class="headers">
-  <h4><%= t(:headers) %></h4>
-  <pre><code class="http"><%= headers.map{ |k,v| "#{k}: #{v}" }.join("\n") %></code></pre>
-</section>
+<% unless headers.blank? %>
+  <section class="headers">
+    <h4><%= t(:headers, scope: :apitome) %></h4>
+    <pre><code class="http"><%= headers.map{ |k,v| "#{k}: #{v}" }.join("\n") %></code></pre>
+  </section>
+<% end %>

data/app/views/apitome/docs/_navigation.html.erb

@@ -2,26 +2,28 @@
   <% if Apitome.configuration.readme %>
     <li>
       <% if Apitome.configuration.single_page %>
-        <a href="#readme"><%= t(:readme) %></a>
+        <a href="#readme"><%= t(:readme, scope: :apitome) %></a>
       <% else %>
-        <a href="<%= Apitome.configuration.mount_at %>"><%= t(:readme) %></a>
+        <a href="<%= Apitome.configuration.mount_at %>"><%= t(:readme, scope: :apitome) %></a>
       <% end %>
     </li>
   <% end %>
   <% resources.each do |resource| %>
     <li>
       <% if Apitome.configuration.single_page %>
-        <a href="#<%= id_for(resource['examples'].first['link']) %>"><%= resource['name'] %></a>
+        <a href="#<%= id_for(resource['name']) %>"><%= resource['name'] %></a>
         <ul class="nav">
           <% resource['examples'].each do |example| %>
             <li><%= link_to example['description'], "##{id_for(example['link'])}" %></li>
           <% end %>
         </ul>
       <% else %>
-        <li><%= link_to resource['name'], "#{Apitome.configuration.mount_at}/#{resource['examples'].first['link'].gsub(/\.json$/, '')}" %></li>
+        <%= link_to resource['name'], resource_link(resource), class: "#{link_active?(resource_link(resource)) ? 'active' : ''}" %>
         <ul class="nav">
           <% resource['examples'].each do |example| %>
-            <li><%= link_to example['description'], "#{Apitome.configuration.mount_at}/#{example['link'].gsub(/\.json$/, '')}" %></li>
+            <li class="<%= link_active?(example_link(example)) ? 'active' : '' %>">
+              <%= link_to example['description'], example_link(example) %>
+            </li>
           <% end %>
         </ul>
       <% end %>

data/app/views/apitome/docs/_params.html.erb

@@ -1,5 +1,5 @@
 <section class="params">
-  <h3><%= t(:parameters) %></h3>
+  <h3><%= t(:parameters, scope: :apitome) %></h3>
   <div class="table-responsive">
     <table class="table table-bordered">
       <tr>
@@ -11,12 +11,12 @@
         <tr>
           <td class="name">
             <% if param['scope'] %>
-              <%= "#{param['scope']}[#{param['name']}]" %>
+              <%= "#{format_scope(param['scope'])}[#{param['name']}]" %>
             <% else %>
               <%= param['name'] %>
             <% end %>
             <% if param['required'] %>
-              <span class="label label-danger required">required</span>
+              <span class="label label-danger required"><%= t(:required, scope: :apitome) %></span>
             <% end %>
           </td>
           <td class="description"><%= param['description'] %></td>

data/app/views/apitome/docs/_query.html.erb

@@ -1,4 +1,4 @@
 <section class="query-parameters">
-  <h4><%= t(:query_parameters) %></h4>
+  <h4><%= t(:query_parameters, scope: :apitome) %></h4>
   <pre><%= request['request_query_parameters'].map{ |k,v| "#{k}=#{v}" }.join("\n") %></pre>
 </section>

data/app/views/apitome/docs/_resource_explanation.html.erb

@@ -0,0 +1,3 @@
+<article class="resource_explanation">
+  <%= raw rendered_markdown(explanation.strip_heredoc) %>
+</article>

data/app/views/apitome/docs/_response_fields.html.erb

@@ -1,5 +1,5 @@
 <section class="params">
-  <h3><%= t(:response_fields) %></h3>
+  <h3><%= t(:response_fields, scope: :apitome) %></h3>
   <div class="table-responsive">
     <table class="table table-bordered">
       <tr>

data/app/views/apitome/docs/_route.html.erb

@@ -1,4 +1,4 @@
 <section class="route">
-  <h4><%= t(:route) %></h4>
+  <h4><%= t(:route, scope: :apitome) %></h4>
   <pre><%= "#{request['request_method']} #{request['request_path']}" %></pre>
 </section>

data/app/views/apitome/docs/_status.html.erb

@@ -1,4 +1,4 @@
 <section class="status">
-  <h4><%= t(:status) %></h4>
+  <h4><%= t(:status, scope: :apitome) %></h4>
   <pre><code class="http"><%= request['response_status'] %></code></pre>
 </section>

data/app/views/apitome/docs/index.html.erb

@@ -5,4 +5,7 @@
     </article>
   </section>
 <% end %>
-<%= render 'all_examples' if Apitome.configuration.single_page %>
+<% if Apitome.configuration.single_page %>
+    <a href="#top" id="scroll-to-top" class="hidden btn btn-primary">Back to Top</a>
+<% end %>
+<%= render 'all_examples' if Apitome.configuration.single_page %>

data/app/views/apitome/docs/show.html.erb

@@ -1,2 +1,3 @@
 <h1 class="resource-name"><%= example['resource'] %></h1>
-<%= render 'example', locals: { example: example, link: example['link'].gsub('.json', '') } %>
+<%= render partial: 'resource_explanation', locals: { explanation: example['resource_explanation'] } if example['resource_explanation'] %>
+<%= render partial: 'example', locals: { example: example, link: example['link'].to_s.gsub('.json', '') } %>

data/config/locales/en.yml

@@ -1,13 +1,15 @@
 en:
-  body: Body
-  curl: cURL
-  headers: Headers
-  parameters: Parameters
-  query_parameters: Query Parameters
-  readme: README
-  request: Request
-  response: Response
-  response_fields: Response Fields
-  route: Route
-  endpoint: Endpoint
-  status: Status
+  apitome:
+    body: Body
+    curl: cURL
+    endpoint: Endpoint
+    headers: Headers
+    parameters: Parameters
+    query_parameters: Query Parameters
+    readme: README
+    request: Request
+    required: required
+    response_fields: Response Fields
+    response: Response
+    route: Route
+    status: Status

data/config/locales/es.yml

@@ -1,12 +1,15 @@
 es:
-  body: Cuerpo
-  curl: cURL
-  headers: Encabezados
-  parameters: Parametros
-  query_parameters: Parámetros de la consulta
-  readme: LEEME
-  request: Solicitud
-  response: Respuesta
-  route: Ruta
-  endpoint: Punto de llegada
-  status: Estado
+  apitome:
+    body: Cuerpo
+    curl: cURL
+    endpoint: Punto de llegada
+    headers: Encabezados
+    parameters: Parametros
+    query_parameters: Parámetros de la consulta
+    readme: LEEME
+    request: Solicitud
+    required: requerido
+    response_fields: Campos de respuesta
+    response: Respuesta
+    route: Ruta
+    status: Estado