api_blueprint 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 3c06b5d206b8bf0f3ca2d9540ce47da6200ff8c5
-  data.tar.gz: 1979c9532714e356234d04858b37b437629d674a
+  metadata.gz: 6ce8f3d792afe506423895b1f7a80c2b63810b82
+  data.tar.gz: 76925ee493aaaae50cd7779bc11db13b02ed11df
 SHA512:
-  metadata.gz: ff4835d306e95aa438ef3cfeaed9e777c3600e0beaaa6f0eb3b5569a544060b19c0c4ed4879eac9bc17bf1e47385c87f9618237c6a837cfb2833e5a5b8e8dd32
-  data.tar.gz: 7811e24b5dfdd4912635ca738657e0c888b12520ae4b5a7cd6f616dd2ca075cfed70dd730c36c275d252075cdd157e454c3ae557be7d2ec250a1872fe1c7342b
+  metadata.gz: 03addbc9798e412cc9190aa447065701ce85c46fd625ac93d2d066b749492098d21511153c211a3dbf6559ec2a77ac49270d53f42fe69729331763737c839b30
+  data.tar.gz: 540918ac22be65b4997a86bad3b03edc55867d84c5c411cec7d8ddb7be702369a04c843a0fc1911dcb7ce2aa762b71c6f9af277532d4ac191df1d89d882159ad

data/lib/api_blueprint/compile/assets/blueprint.js

@@ -0,0 +1,387 @@
+(function() { 'use strict';
+  $(function() {
+    var docTitle = $('title').text();
+    var addLinkToHistory = false;
+
+    /* init href position */
+
+    var href = window.location.href.split('#')[1];
+    if (href) {
+      var target = $('#' + href);
+      if (target.length == 0) {
+        href = href.replace(/^\d+\-/g, '');
+        target = $('#' + href);
+      }
+
+      if (target.length) {
+        $('html, body').scrollTop( target.offset().top - 20 );
+
+        $(window).load(function() {
+          $('html, body').scrollTop( target.offset().top - 20 );
+
+          var interval = null, i = 0;
+
+          interval = setInterval(function() {
+            $('html, body').scrollTop( target.offset().top - 20 );
+            ++i;
+
+            if (i > 100) {
+              clearInterval(interval);
+            }
+          }, 10);
+        });
+      }
+    }
+
+    /* wrap contents */
+
+    var wrapFromTo = function(container, from, to) {
+      $(from).each(function() {
+        var starter = $(this);
+        var wrapper = $(container);
+        var content = starter.nextUntil(to);
+
+        starter.before(wrapper);
+        wrapper.append(starter);
+        wrapper.append(content);
+      });
+    };
+
+    wrapFromTo('<div class="toc">', "h1:contains('Table Of Contents')", 'h1');
+    wrapFromTo('<div class="resource">', "h1:contains('Resource: ')", 'h1, p.footer');
+    wrapFromTo('<div class="action">', ".resource > h2:contains('Action: ')", 'h2');
+    wrapFromTo('<div class="description">', ".action > h3:contains('Description:')", 'h3:contains("Examples")');
+    wrapFromTo('<div class="examples">', ".action > h3:contains('Examples:')", 'h3');
+    wrapFromTo('<div class="example">', ".examples > h4:contains('Example: ')", 'h4');
+
+    /* highlighting active toc */
+
+    var markTocActive = function() {
+      var pos = $(window).scrollTop() + 30;
+
+      var resources = $('h1');
+      var pickResource = resources[0]; // null;
+      resources.each(function() {
+        if ($(this).offset().top > pos) {
+          return false;
+        }
+        pickResource = this;
+      });
+
+      var tocLinks = $('.toc a');
+      tocLinks.removeClass('active');
+
+      var actions = $('h2');
+      var pickAction = null;
+      actions.each(function() {
+        if ($(this).offset().top > pos) {
+          return false;
+        }
+        pickAction = this;
+      });
+
+      if (pickAction) {
+        var id = $(pickAction).attr('id');
+        var tocActionLink = $('.toc a[href="#' + id + '"]');
+
+        tocActionLink.addClass('active');
+      }
+
+      if (pickResource) {
+        var id = $(pickResource).attr('id');
+        var tocLink = $('.toc a[href="#' + id + '"]');
+
+        var currentTocSection = tocLink.closest('li');
+        var otherSections = currentTocSection.siblings();
+        var activeChildren = currentTocSection.find('ul li a.active').length > 0;
+
+        tocLink.addClass('active');
+        tocLink.toggleClass('active-children',
+          activeChildren);
+        otherSections.find('a').removeClass('active');
+
+        currentTocSection.children('ul').slideDown();
+        otherSections.children('ul').slideUp();
+
+        if (history && history.replaceState) {
+          if (activeChildren) {
+            var newHash = tocActionLink.attr('href').split('#')[1];
+            var newTitle = tocActionLink.text() + ' - ' + tocLink.text() + ' - ' + docTitle;
+          } else {
+            var newHash = tocLink.attr('href').split('#')[1];
+            var newTitle = tocLink.text()  + ' - ' + docTitle;
+          }
+
+          if (window.location.hash.split('#')[1] != newHash || document.title != newTitle) {
+            document.title = newTitle;
+
+            var newUrl = window.location.href.split('#')[0] + '#' + newHash;
+            var newData = { hash: newHash };
+
+            if (addLinkToHistory) {
+              history.pushState(newData, newTitle, newUrl);
+
+              addLinkToHistory = false;
+            } else {
+              history.replaceState(newData, newTitle, newUrl);
+            }
+          }
+        }
+      }
+    };
+
+    $(window).scroll(markTocActive);
+    markTocActive();
+
+    /* scroll for toc links */
+
+    var scrollToTarget = function(target) {
+      if (target.length < 1) {
+        return;
+      }
+
+      var position = target.offset().top;
+
+      $('html, body').scrollTop( position + 80 ).animate({
+        scrollTop: position - 20
+      });
+    };
+
+    var scrollToLinkTarget = function(link) {
+      addLinkToHistory = true;
+
+      var selector = link.attr('href');
+      var target = $(selector);
+
+      scrollToTarget(target);
+
+      return false;
+    };
+
+    window.onpopstate = function(event) {
+      var hash = event.state.hash;
+      if (!hash) {
+        return;
+      }
+
+      var target = $('#' + hash);
+      setTimeout(function() {
+        scrollToTarget(target);
+      }, 0);
+    };
+
+    /* prettify code */
+
+    $('pre').addClass('prettyprint');
+    $('h5:contains("headers:") + pre').removeClass('prettyprint');
+
+    /* generate the curl requests */
+
+    var getHost = function() {
+      var host = $('#host');
+
+      if (host.length && host.text().substr(0, 4) === 'http') {
+        return host.text();
+      } else if (window.location.host.length) {
+        return window.location.protocol + '//' + window.location.host;
+      } else {
+        return 'http://www.example.com';
+      }
+    };
+
+    var generateCurlExample = function(exampleContent) {
+      if (exampleContent.find('.curl').length) {
+        return;
+      }
+
+      var actionContent = exampleContent.closest('.action');
+      var method = actionContent.find('h4:contains("Signature:") + p > strong').text().toUpperCase();
+      if (method !== 'GET' && method !== 'POST' && method !== 'PATCH' && method !== 'DELETE') {
+        return;
+      }
+
+      var path = actionContent.find('h4:contains("Signature:") + p > code').text();
+      if (path[0] !== '/') {
+        return;
+      }
+
+      var headers   = exampleContent.find('h5:contains("Request headers:") + pre').text();
+      var params    = exampleContent.find('h5:contains("Request params:") + pre').text();
+      var rawInfo   = exampleContent.children('h5:contains("Request"), h5:contains("Request") + pre');
+      var prefix    = '     ', suffix = ' \\\\\n', curl = '';
+      var multipart = !! headers.match(/multipart/);
+
+      var rawWrapper = $('<div class="raw"></div>');
+      exampleContent.children('h4').after(rawWrapper);
+      rawWrapper.append(rawInfo);
+
+      curl += 'curl --include' + suffix;
+      curl += prefix + '--request ' + method + suffix;
+
+      if (headers) {
+        headers.split("\n").forEach(function(header) {
+          if (header.length) {
+            curl += prefix + '--header "' + header.replace(/\s+/, ' ') + '"' + suffix;
+          }
+        });
+      }
+
+      if (params && method !== 'GET') {
+        if (multipart) {
+          $.each($.param($.parseJSON(params)).split("&"), function(index, param) {
+            var file = decodeURIComponent(param).match(/\S+\+\<(\S+?)\>/);
+
+            if (file) {
+              curl += prefix + '--form "' + decodeURIComponent(param).split('=')[0] + '=@' + file[1] + '"' + suffix;
+            } else {
+              curl += prefix + '--form "' + decodeURIComponent(param) + '"' + suffix;
+            }
+          });
+        } else {
+          curl += prefix + "--data-binary '" + params.replace(/\n+$/, '') + "'" + suffix;
+        }
+      }
+
+      curl += prefix + '"' + getHost() + path;
+      if (params && method === 'GET') {
+        curl += '?' + $.param($.parseJSON(params)).replace(/&/g, '&amp;');
+      }
+      curl += '"';
+
+      exampleContent.children('h4').after('<div class="curl"><h5>Request in cURL:</h5><pre><code>' + curl + '</code></pre></div>');
+
+      var controls = $("<span class='format-toggle'><a class='as-raw' href=''>Raw</a><a class='as-curl' href=''>cURL</a></span>");
+      exampleContent.find('> div h5:first-child').append(controls);
+    }
+
+    $(document).on('click', '.format-toggle a', function() {
+      $('html').toggleClass('example-curl', $(this).hasClass('as-curl'));
+
+      return false;
+    });
+
+    /* example unfolding */
+
+    $(document).on('click', '.example > h4', function() {
+      var thisExample = $(this).closest('.example');
+
+      $('.example').not(thisExample).removeClass('visible');
+      thisExample.toggleClass('visible');
+
+      if (thisExample.hasClass('visible')) {
+        generateCurlExample(thisExample);
+
+        $('html, body').animate({
+          scrollTop: thisExample.offset().top - 20
+        });
+      }
+
+      return false;
+    });
+
+    $('h5:contains("Response headers:") + pre').filter(function(item) {
+      var status = $(this).text().match(/Status\:\s*(\d+)/)[1];
+
+      return (status && parseInt(status) > 0 && parseInt(status) >= 400);
+    }).closest('.example').addClass('failed');
+
+    /* cut unnecessary texts */
+
+    $('.example > h4').each(function(header) {
+      $(this).text($(this).text().replace('Example: ', ''))
+    });
+
+    /* add example status descriptions */
+
+    $('.examples').append("<p class='example-description'>Examples that depict proper requests resulting in status 200 are marked with <em class='green'>green dots</em>, while those that depict wrong usage are marked with <em class='red'>red dots</em>.</p>")
+
+    /* add & handle the toc hider */
+
+    var tocHider = $('<a href="#" class="toc-hider"></a>');
+    var tocHeader = $('.toc h1');
+    tocHeader.after(tocHider);
+    tocHider.append(tocHeader);
+
+    tocHider.click(function() {
+      $('html').toggleClass('hide-toc');
+
+      return false;
+    });
+
+    /* mark js */
+
+    $('html').addClass('js');
+
+    /* handle param table */
+
+    $('h4:contains("Parameters:") + table').addClass('parameters');
+
+    $('table.parameters td:contains("[]")').each(function() {
+      var td = $(this),
+          level = td.text().match(/\[\]/g).length + 1,
+          row = td.closest('tr');
+
+      td.text(td.text().replace(/\[\]/g, ''));
+      row.addClass('param-level-' + level);
+    });
+
+    $('table.parameters code:contains("Example:")').addClass('example').each(function() {
+      $(this).text($(this).text().replace("Example:", ''));
+    });
+
+    $('table.parameters td:nth-child(2) strong:contains("required")').addClass("required");
+
+    /* Autolink */
+
+    $('a[href="#menu"]').addClass('menu-autolink');
+
+    $(document).on('click', 'a[href="#menu"]', function() {
+      var link = $(this);
+      var text = link.text();
+      var targetLink = $('.toc a:contains("' + text + '")');
+
+      if (targetLink.length) {
+        if (targetLink.length > 1) {
+          targetLink.each(function() {
+            var eachLink = $(this);
+
+            if (eachLink.text() == text) {
+              targetLink = eachLink;
+              return false;
+            }
+          });
+        }
+
+        link.attr('href', targetLink.attr('href'));
+
+        return scrollToLinkTarget(targetLink);
+      }
+
+      return false;
+    });
+
+    $('a[href="#example"]').addClass('example-autolink');
+
+    $(document).on('click', 'a[href="#example"]', function(e) {
+      var link = $(this);
+      var text = link.text();
+      var target = $('.example h4:contains("' + text + '")');
+
+      if (target.length) {
+        scrollToTarget(target);
+
+        if (! target.closest('.example').hasClass('visible')) {
+          target.click();
+        }
+      }
+
+      return false;
+    });
+
+    $(document).on('click', 'a[href^="#"]', function() {
+      return scrollToLinkTarget($(this));
+    });
+  });
+})();
+
+

data/lib/api_blueprint/compile/assets/blueprint.scss

@@ -0,0 +1,172 @@
+$lead: rgb(204, 17, 67);
+$code: rgb(240, 230, 140);
+$succ: rgb(152, 251, 152);
+$fail: rgb(255, 160, 160);
+
+$toc-width: 200px;
+
+#title, #host, #copyright { display: none; }
+
+html, body { background: #eee; font-family: Helvetica, "Trebuchet MS", Arial, sans-serif; padding: 0; margin: 0; font-size: 14px; }
+code { font-family: "Lucida Console", Monaco, monospace; }
+@media screen {
+  html.js body { padding-left: $toc-width; }
+}
+
+html.hide-toc {
+  body { padding-left: 0; }
+  .toc { bottom: auto; opacity: 0; border-bottom: 1px solid #ccc; box-shadow: 0px 0px 20px #888;
+    &:hover { opacity: 1; }
+    ul { display: none; }
+  }
+}
+
+a { text-decoration: none; color: $lead; }
+a:hover { text-decoration: underline; }
+h1, h2, h3, h4, h5 { font-weight: 300; margin: 20px; color: $lead; }
+p { margin: 20px; }
+p, li, td { line-height: 1.4em; }
+pre { margin: 20px; padding: 5px; overflow-x: auto; background: #111 !important; color: $code; }
+li { margin: 5px 0; }
+ul ul { padding-left: 20px; }
+
+table { text-align: left; width: 100%; border-spacing: 0; margin: 20px 0; margin-left: 10px;
+  p { margin: 0; }
+  span.param-level { display: none; }
+  td, th { padding: 8px 10px; vertical-align: top; }
+  th { font-size: 1em; font-weight: normal; color: #999; text-transform: uppercase; padding: 4px 10px;  }
+  td { border-top: 1px solid #bbb; }
+}
+
+table.parameters {
+  tr.param-level-2 {
+    td { border-top-color: transparent; }
+    td:first-child { padding-left: 20px; }
+  }
+  tr.param-level-3 {
+    td { border-top-color: transparent; }
+    td:first-child { padding-left: 30px; }
+  }
+  tr.param-level-4 {
+    td { border-top-color: transparent; }
+    td:first-child { padding-left: 40px; }
+  }
+  code.example { display: block; word-wrap: break-word; color: #999; max-width: 120px; font-size: 0.9em; }
+  td:first-child { font-weight: bold; }
+  strong.required { color: $lead; display: block; }
+}
+
+a.menu-autolink, a.example-autolink {
+  &:before { margin-right: 1px; background: rgba($lead, 0); border-radius: 100px; text-decoration: none !important; width: 1.25em; display: inline-block; text-align: center; font-weight: bold; transition: 0.15s; }
+  &:hover:before { background: $lead; color: white; }
+}
+
+a.menu-autolink {
+  &:before { content: '☍'; }
+}
+
+a.example-autolink {
+  &:before { content: '✎'; }
+}
+
+@media screen {
+  blockquote { margin: 20px; background: #fff; overflow: hidden; border: 1px solid #ccc; box-shadow: 4px 0px 0px $lead inset;
+    p { margin: 10px 20px; }
+  }
+
+  .toc { position: fixed; left: 0; top: 0; bottom: 0; width: $toc-width; z-index: 10; overflow-y: auto; background: #f5f5f5; border-right: 1px solid #ccc; transition: opacity 0.3s; font-size: 0.9em;
+    h1 { font-size: 1.1em; }
+    ul li { margin: 0;
+      a { padding: 4px 10px; transition: 0.15s; line-height: 1.2em; white-space: nowrap; text-overflow: ellipsis; overflow: hidden;
+        &:hover { text-decoration: none; box-shadow: -2px 0px 0px 0px #bbb inset; }
+        &.active { color: #000; }
+        &.active:not(.active-children) { box-shadow: -2px 0px 0px 0px $lead inset; }
+      }
+    }
+    > ul { list-style-type: none; margin: 0; padding-left: 0;
+      > li {
+          > a { font-size: 1em; text-transform: uppercase; margin: 0; display: block; color: #999;
+        }
+        > ul { list-style-type: none; padding-left: 0; padding-bottom: 20px; padding-top: 0px; display: none;
+          > li > a { font-size: 1.0em; display: block; padding-left: 20px; color: #888;
+          }
+        }
+      }
+    }
+  }
+}
+
+@media print {
+  html, body { height: 100%; }
+
+  #title, #copyright { display: block; }
+  #title { font-size: 2em; color: $lead; padding-top: 50%; margin-top: 60px; }
+  #copyright { page-break-after: always; }
+
+  p.footer.copyright { display: none; }
+
+  h1 { page-break-before: always; }
+  .toc h1 { page-break-before: auto; }
+  .examples {
+    .example-description { display: none; }
+    .example { display: none; }
+    .example:nth-child(2) { display: block; }
+
+    &:after { content: 'Refer to online documentation for more examples on this action\'s usage.'; display: block; margin: 20px; font-weight: 300; }
+  }
+  table { padding: 0 20px; }
+}
+
+@media screen {
+  .resource { clear: both; position: relative; z-index: 1;
+    .action { clear: both; border-bottom: 1px solid #ccc; overflow: hidden;
+      h3 { text-transform: uppercase; }
+
+      .description { float: left; width: 50%; background: #fff; border-top: 1px solid #ccc; position: relative;
+        blockquote { background: #eee; }
+      }
+      .examples { float: right; width: 50%; color: #fff; background: #333; border-top: 1px solid #ccc; position: relative;
+        .example-description { color: #888; font-style: italic; margin-top: 15px; margin-bottom: 15px;
+          em { color: #aaa; white-space: nowrap; font-style: normal; }
+          em:before { content: ' '; display: inline-block; height: 10px; width: 10px; border-radius: 5px; margin-right: 3px; background: $succ; }
+          em.red:before { background: $fail; }
+        }
+        h3 { color: #eee; margin-bottom: 13px; }
+        h5 { color: #888; text-transform: uppercase; }
+        .example.visible {
+          > * { display: block; }
+        }
+        .example {
+          > * { display: none; margin: 20px; }
+          > h4 { display: block; cursor: pointer; color: #ddd; font-size: 1em; padding: 7px 20px 7px 40px; position: relative; margin: 0; transition: 0.15s; }
+          > h4:before { position: absolute; top: 50%; margin-top: -5px; left: 20px; height: 10px; width: 10px; border-radius: 5px; background: $succ; display: block; content: ' '; }
+          > h4:hover { color: #fff; background: #4c4c4c; }
+          > .curl, > .raw { margin: 0; }
+          > .curl { display: none; }
+        }
+
+        .example.failed > h4:before { background: $fail; }
+      }
+
+      .description:after, .examples:after { position: absolute; top: 100%; height: 10000px; left: 0; right: 0; background: #fff; content: ' '; }
+      .examples:after { background: #333; }
+    }
+  }
+}
+
+.format-toggle { float: right;
+  a { color: #888; margin-left: 5px; }
+  .as-raw { color: #bbb; }
+}
+
+html.example-curl .resource .action .examples .example.visible {
+  > .curl { display: block; }
+  > .raw { display: none; }
+  .format-toggle {
+    .as-raw { color: #888; }
+    .as-curl { color: #bbb; }
+  }
+}
+
+p.footer { text-align: center; color: #888; clear: both; }
+

data/lib/api_blueprint/compile/assets/index.html

@@ -0,0 +1,23 @@
+<!DOCTYPE html>
+
+<html lang="en">
+  <head>
+    <title>Visuality API</title>
+
+    <meta charset="utf-8">
+
+    <style id="blueprint-style"></style>
+
+    <script type="text/javascript" src="https://code.jquery.com/jquery-1.11.1.min.js"></script>
+    <script id="blueprint-script"></script>
+    <script type="text/javascript" src="https://google-code-prettify.googlecode.com/svn/loader/run_prettify.js?skin=desert"></script>
+  </head>
+
+  <body>
+    <div id="blueprint-document">
+    </div>
+
+    <p class='footer copyright'>© Visuality</p>
+  </body>
+</html>
+

data/lib/api_blueprint/version.rb

@@ -1,3 +1,3 @@
 module ApiBlueprint
-  VERSION = '0.1.0'
+  VERSION = '0.1.1'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: api_blueprint
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Karol Słuszniak
@@ -80,12 +80,8 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: You start with method list generated from RSpec request specs. For each
-  method, you get a list of parameters and examples. Then, you can extend it in whatever
-  way you need using Markdown syntax. You can organize documentation files into partials.
-  Upon any API change, like serializer change that changes responses, you can update
-  automatically generated parts of docs. Once done, you can compile your documentation
-  into single, nicely styled HTML file. You can also auto-deploy it via SSH.
+description: Semi-automatic solution for creating Rails app's API documentation based
+  on RSpec request specs.
 email: k.sluszniak@visuality.pl
 executables: []
 extensions: []
@@ -100,6 +96,9 @@ files:
 - lib/api_blueprint/collect/renderer.rb
 - lib/api_blueprint/collect/spec_hook.rb
 - lib/api_blueprint/collect/storage.rb
+- lib/api_blueprint/compile/assets/blueprint.js
+- lib/api_blueprint/compile/assets/blueprint.scss
+- lib/api_blueprint/compile/assets/index.html
 - lib/api_blueprint/compile/compile.rb
 - lib/api_blueprint/compile/storage.rb
 - lib/api_blueprint/railtie.rb