api_guides 0.1.0

data/lib/api_guides/reference.rb

@@ -0,0 +1,42 @@
+# -*- encoding: utf-8 -*-
+
+module ApiGuides
+  # This class models a <reference> element in a document.
+  # It will always be shown with the associated section.
+  # All references will be combined into an index.
+  #
+  # References can also be linked to using standard
+  # markdown syntax with some sugar provided by this
+  # library.
+  #
+  # Each reference has a title. The title is used for linking
+  # and descirbing each reference. You should markdown
+  # inside each reference to fill in your content
+  class Reference
+    attr_accessor :title, :content
+
+    def initialize(attributes = {})
+      attributes.each_pair do |attr, value|
+        send "#{attr}=", value
+      end
+    end
+
+    # Takes an XML representation and parse
+    # it into a Reference instance. 
+    # 
+    # Here is XML format expected:
+    #
+    #     <reference title="Foo">
+    #       <![CDATA[
+    #       Insert your markdown here
+    #       ]]>
+    #     </reference>
+    #
+    # This would set `#title` to 'Foo'
+    # and #content to 'Insert your markdown here'
+    def self.from_xml(xml)
+      doc = Nokogiri::XML.parse(xml).at_xpath('//reference')
+      Reference.new :title => doc.attributes['title'].try(:value), :content => doc.content
+    end
+  end
+end

data/lib/api_guides/resources/style.css

@@ -0,0 +1,258 @@
+body {
+  font-family: 'Palatino Linotype', 'Book Antiqua', Palatino, FreeSerif, serif;
+  font-size: 15px;
+  line-height: 22px;
+  color: #252519;
+  margin: 0; padding: 0;
+}
+a {
+  color: #0069D6;
+  text-decoration: none;
+}
+  a:visited {
+    color: #0069D6;
+  }
+p {
+  margin: 0 0 15px 0;
+}
+h1, h2, h3, h4, h5, h6 {
+  margin: 0px 0 15px 0;
+}
+#container {
+  position: relative;
+}
+#background {
+  position: fixed;
+  top: 0; left: 525px; right: 0; bottom: 0;
+  background: #f5f5ff;
+  border-left: 1px solid #e5e5ee;
+  z-index: -1;
+}
+#jump_to, #jump_page {
+  background: white;
+  -webkit-box-shadow: 0 0 25px #777; -moz-box-shadow: 0 0 25px #777;
+  -webkit-border-bottom-left-radius: 5px; -moz-border-radius-bottomleft: 5px;
+  font: 10px Arial;
+  text-transform: uppercase;
+  cursor: pointer;
+  text-align: right;
+}
+#jump_to, #jump_wrapper {
+  position: fixed;
+  right: 0; top: 0;
+  padding: 5px 10px;
+}
+  #jump_wrapper {
+    padding: 0;
+    display: none;
+  }
+    #jump_to:hover #jump_wrapper {
+      display: block;
+    }
+    #jump_page {
+      padding: 5px 0 3px;
+      margin: 0 0 25px 25px;
+    }
+      #jump_page .source {
+        display: block;
+        padding: 5px 10px;
+        text-decoration: none;
+        border-top: 1px solid #eee;
+      }
+        #jump_page .source:hover {
+          background: #f5f5ff;
+        }
+        #jump_page .source:first-child {
+        }
+table td {
+  border: 0;
+  outline: 0;
+}
+  td.docs, th.docs {
+    max-width: 450px;
+    min-width: 450px;
+    min-height: 5px;
+    padding: 10px 25px 1px 50px;
+    overflow-x: hidden;
+    vertical-align: top;
+    text-align: left;
+  }
+    .docs pre {
+      margin: 15px 0 15px;
+      padding-left: 15px;
+    }
+    .docs p tt, .docs p code, .docs li code, .docs dd code {
+      background: #f8f8ff;
+      border: 1px solid #dedede;
+      font-size: 12px;
+      padding: 0 0.2em;
+    }
+    .pilwrap {
+      position: relative;
+    }
+      .pilcrow {
+        font: 12px Arial;
+        text-decoration: none;
+        color: #454545;
+        position: absolute;
+        top: 3px; left: -20px;
+        padding: 1px 2px;
+        opacity: 0;
+        -webkit-transition: opacity 0.2s linear;
+      }
+        td.docs:hover .pilcrow {
+          opacity: 1;
+        }
+  td.code, th.code {
+    padding: 14px 15px 16px 25px;
+    width: 100%;
+    vertical-align: top;
+    background: #f5f5ff;
+    border-left: 1px solid #e5e5ee;
+  }
+    pre, tt, code {
+      font-size: 12px; line-height: 18px;
+      font-family: Menlo, Monaco, Consolas, "Lucida Console", monospace;
+      margin: 10px 0;
+      padding: 0;
+    }
+
+  td.code pre,
+  td.code tt,
+  td.code code,
+  th.code pre,
+  th.code tt,
+  th.code code {
+    font-size: 14px;
+  }
+
+
+body {
+  padding-top: 50px;
+}
+
+#logo { 
+  float: right;
+  position: relative;
+  top: 7px;
+}
+
+td.docs dl {
+  overflow: auto;
+}
+
+td.docs dt {
+  clear: both;
+  width: 35%;
+  float: left;
+  text-align: right;
+  font-weight: bold;
+  margin-top: 8px;
+}
+
+td.docs dd {
+  float: left;
+  width: 60%;
+  padding-left: 8px;
+  margin-left: 0;
+  margin-top: 8px;
+}
+
+#topbar a.brand {
+  float: left;
+  display: block;
+  padding: 8px 20px 12px;
+  margin-left: -20px;
+  color: white;
+  font-size: 20px;
+  font-weight: 200;
+  line-height: 1;
+  font-family: 'Helvetica Neue', Helvetica, Arial, sans-serif;
+}
+
+#topbar .nav {
+  display: block;
+  float: left;
+  margin: 0 10px 0 0;
+  position: relative;
+  left: 0;
+  list-style: none
+}
+
+#topbar .nav > li > a {
+  display: block;
+  float: none;
+  padding: 10px 10px 11px;
+  line-height: 19px;
+  text-decoration: none;
+  color: #BFBFBF;
+  font-size: 13px;
+  text-decoration: none;
+  font-family: 'Helvetica Neue', Helvetica, Arial, sans-serif;
+}
+
+#topbar .nav > li > a:hover,
+#topbar a.brand:hover {
+  background-color: rgba(255, 255, 255, 0.05);
+  color: white;
+  text-decoration: none;
+}
+
+#toc:hover #table-of-contents {
+  display: block;
+}
+
+#table-of-contents {
+  display: none;
+  width: 960px; 
+  margin-left: 50px;
+  border-left: 1px solid #BBB;
+  border-right: 1px solid #BBB;
+  border-bottom: 1px solid #BBB;
+  background-color: white;
+  overflow: auto;
+  position: absolute;
+  top: 40px;
+  padding: 20px 0;
+  z-index: 100;
+}
+
+#table-of-contents section {
+  width: 280px;
+  float: left;
+  margin-left: 20px;
+}
+
+#table-of-contents .sub-section a,
+#table-of-contents .sub-section a:visited  {
+  color: inherit;
+}
+
+#table-of-contents .header {
+  font-weight: bold;
+  font-size: 17px;
+  text-transform: uppercase;
+}
+
+#topbar {
+  height: 40px;
+  position: fixed;
+  top: 0;
+  left: 0;
+  right: 0;
+  z-index: 10000;
+  background-color: #222;
+  background-repeat: repeat-x;
+  background-image: -khtml-gradient(linear, left top, left bottom, from(#333333), to(#222222));
+  background-image: -moz-linear-gradient(top, #333333, #222222);
+  background-image: -ms-linear-gradient(top, #333333, #222222);
+  background-image: -webkit-gradient(linear, left top, left bottom, color-stop(0%, #333333), color-stop(100%, #222222));
+  background-image: -webkit-linear-gradient(top, #333333, #222222);
+  background-image: -o-linear-gradient(top, #333333, #222222);
+  background-image: linear-gradient(top, #333333, #222222);
+  filter: progid:DXImageTransform.Microsoft.gradient(startColorstr='#333333', endColorstr='#222222', GradientType=0);
+  -webkit-box-shadow: 0 1px 3px rgba(0, 0, 0, 0.25), inset 0 -1px 0 rgba(0, 0, 0, 0.1);
+  -moz-box-shadow: 0 1px 3px rgba(0, 0, 0, 0.25), inset 0 -1px 0 rgba(0, 0, 0, 0.1);
+  box-shadow: 0 1px 3px rgba(0, 0, 0, 0.25), inset 0 -1px 0 rgba(0, 0, 0, 0.1);
+  padding-left: 50px;
+}

data/lib/api_guides/resources/syntax.css

@@ -0,0 +1,64 @@
+/*---------------------- Syntax Highlighting -----------------------------*/
+td.linenos { background-color: #f0f0f0; padding-right: 10px; }
+span.lineno { background-color: #f0f0f0; padding: 0 5px 0 5px; }
+body .hll { background-color: #ffffcc }
+body .c { color: #408080; font-style: italic }  /* Comment */
+body .err { border: 1px solid #FF0000 }         /* Error */
+body .k { color: #954121 }                      /* Keyword */
+body .o { color: #666666 }                      /* Operator */
+body .cm { color: #408080; font-style: italic } /* Comment.Multiline */
+body .cp { color: #BC7A00 }                     /* Comment.Preproc */
+body .c1 { color: #408080; font-style: italic } /* Comment.Single */
+body .cs { color: #408080; font-style: italic } /* Comment.Special */
+body .gd { color: #A00000 }                     /* Generic.Deleted */
+body .ge { font-style: italic }                 /* Generic.Emph */
+body .gr { color: #FF0000 }                     /* Generic.Error */
+body .gh { color: #000080; font-weight: bold }  /* Generic.Heading */
+body .gi { color: #00A000 }                     /* Generic.Inserted */
+body .go { color: #808080 }                     /* Generic.Output */
+body .gp { color: #000080; font-weight: bold }  /* Generic.Prompt */
+body .gs { font-weight: bold }                  /* Generic.Strong */
+body .gu { color: #800080; font-weight: bold }  /* Generic.Subheading */
+body .gt { color: #0040D0 }                     /* Generic.Traceback */
+body .kc { color: #954121 }                     /* Keyword.Constant */
+body .kd { color: #954121; font-weight: bold }  /* Keyword.Declaration */
+body .kn { color: #954121; font-weight: bold }  /* Keyword.Namespace */
+body .kp { color: #954121 }                     /* Keyword.Pseudo */
+body .kr { color: #954121; font-weight: bold }  /* Keyword.Reserved */
+body .kt { color: #B00040 }                     /* Keyword.Type */
+body .m { color: #666666 }                      /* Literal.Number */
+body .s { color: #219161 }                      /* Literal.String */
+body .na { color: #7D9029 }                     /* Name.Attribute */
+body .nb { color: #954121 }                     /* Name.Builtin */
+body .nc { color: #0000FF; font-weight: bold }  /* Name.Class */
+body .no { color: #880000 }                     /* Name.Constant */
+body .nd { color: #AA22FF }                     /* Name.Decorator */
+body .ni { color: #999999; font-weight: bold }  /* Name.Entity */
+body .ne { color: #D2413A; font-weight: bold }  /* Name.Exception */
+body .nf { color: #0000FF }                     /* Name.Function */
+body .nl { color: #A0A000 }                     /* Name.Label */
+body .nn { color: #0000FF; font-weight: bold }  /* Name.Namespace */
+body .nt { color: #954121; font-weight: bold }  /* Name.Tag */
+body .nv { color: #19469D }                     /* Name.Variable */
+body .ow { color: #AA22FF; font-weight: bold }  /* Operator.Word */
+body .w { color: #bbbbbb }                      /* Text.Whitespace */
+body .mf { color: #666666 }                     /* Literal.Number.Float */
+body .mh { color: #666666 }                     /* Literal.Number.Hex */
+body .mi { color: #666666 }                     /* Literal.Number.Integer */
+body .mo { color: #666666 }                     /* Literal.Number.Oct */
+body .sb { color: #219161 }                     /* Literal.String.Backtick */
+body .sc { color: #219161 }                     /* Literal.String.Char */
+body .sd { color: #219161; font-style: italic } /* Literal.String.Doc */
+body .s2 { color: #219161 }                     /* Literal.String.Double */
+body .se { color: #BB6622; font-weight: bold }  /* Literal.String.Escape */
+body .sh { color: #219161 }                     /* Literal.String.Heredoc */
+body .si { color: #BB6688; font-weight: bold }  /* Literal.String.Interpol */
+body .sx { color: #954121 }                     /* Literal.String.Other */
+body .sr { color: #BB6688 }                     /* Literal.String.Regex */
+body .s1 { color: #219161 }                     /* Literal.String.Single */
+body .ss { color: #19469D }                     /* Literal.String.Symbol */
+body .bp { color: #954121 }                     /* Name.Builtin.Pseudo */
+body .vc { color: #19469D }                     /* Name.Variable.Class */
+body .vg { color: #19469D }                     /* Name.Variable.Global */
+body .vi { color: #19469D }                     /* Name.Variable.Instance */
+body .il { color: #666666 }                     /* Literal.Number.Integer.Long */

data/lib/api_guides/section.rb

@@ -0,0 +1,65 @@
+# -*- encoding: utf-8 -*-
+
+module ApiGuides
+  # This class is simply a structure to hold the docs
+  # and the examples.
+  #
+  # Sections require docs, but do not require
+  # any examples. Set examples when you want
+  # those on the right side of the docs.
+  #
+  # You never interact with this class directly.
+  class Section
+    attr_accessor :docs, :examples, :reference, :title
+
+    def initialize(attributes = {})
+      attributes.each_pair do |attr, value|
+        send "#{attr}=", value
+      end
+    end
+
+    # Takes an XML representation and parse
+    # it into a section instance. 
+    # 
+    # Here is XML format expected:
+    #
+    #     <section title="Foo">
+    #       <docs>
+    #         <![CDATA[
+    #         Insert your markdown here
+    #         ]]>
+    #       </docs>
+    #       <reference title="Bar">
+    #         <![CDATA[
+    #         Insert your markdown here
+    #         ]]>
+    #       </reference>
+    #       <examples>
+    #         <example language="ruby">
+    #           <![CDATA[
+    #           Insert your markdown here>
+    #           ]]>
+    #         </example>
+    #       </example>
+    #     </section>
+    #
+    # It also loops instantiates the Reference
+    # and examples if they are given using their
+    # `from_xml` methods as well
+    def self.from_xml(xml)
+      doc = Nokogiri::XML.parse(xml).at_xpath('//section')
+      section = Section.new :title => doc.attributes['title'].try(:value)
+      section.docs = doc.at_xpath('./docs').content if doc.at_xpath('./docs')
+
+      if reference_xml = doc.at_xpath('./reference')
+        section.reference = Reference.from_xml(reference_xml.to_s)
+      end
+
+      section.examples = doc.xpath('//example').map do |example_xml|
+        Example.from_xml example_xml.to_s
+      end
+
+      section
+    end
+  end
+end

data/lib/api_guides/templates/page.mustache

@@ -0,0 +1,80 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <meta http-equiv="content-type" content="text/html;charset=utf-8">
+  <title>{{ title }}</title>
+  <link rel="stylesheet" type="text/css" href="./syntax.css" />
+  <link rel="stylesheet" type="text/css" href="./style.css" />
+</head>
+<body>
+
+<div id="topbar">
+  {{#logo}}
+    <img id="logo" src="{{ logo }}"/>
+  {{/logo}}
+
+  <a href="#" class="brand">{{ title }}</a>
+
+  <ul class="nav">
+    <li id="toc">
+      <a href="#">Table of Contents</a>
+      <div id="table-of-contents">
+        {{#documents}}
+          <section>
+            <a class="header" href="#{{id}}">{{title}}</a>
+            <ol>
+              {{#sections}}
+                {{#title}}
+                  <li class="sub-section"><a href="#{{id}}">{{title}}</a></li>
+                {{/title}}
+              {{/sections}}
+            </ol>
+          </section>
+        {{/documents}}
+      </div>
+    </li>
+    {{#links}}
+      <li><a href="#{{href}}">{{name}}</a></li>
+    {{/links}}
+  </ul>
+</div>
+
+
+<div id="container">
+  <div id="background"></div>
+  {{#documents}}
+    <table cellspacing="0" cellpadding="0">
+      <thead>
+        <tr>
+          <th class="docs">
+            <h1 id="{{id}}">{{title}}</h1>
+          </th>
+          <th class="code">&nbsp;</th>
+        </tr>
+      </thead>
+      <tbody>
+        {{#sections}}
+          <tr>
+            <td class="docs">
+              <h2 id="{{id}}">{{title}}</h2>
+
+              {{{ docs }}}
+            </td>
+            <td class="code">
+              {{#reference}}
+                <h2 id="{{id}}">{{title}}</h2>
+                {{{ content }}}
+              {{/reference}}
+
+              {{#examples}}
+                {{{ content }}}
+              {{/examples}}
+            </td>
+          </tr>
+        {{/sections}}
+      <tbody>
+    </table>
+  {{/documents}}
+</div>
+</body>
+</html>