raddocs 0.5.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 51c3f683fc4b32ffe21f3b00883e54ede5f9874d
-  data.tar.gz: 04fb0bab660edaca38e10723ac9a7ab16ff2b795
+  metadata.gz: 5b989901e3d45fb5255c8c9222d1746879b9790b
+  data.tar.gz: cc742b1983b7f2e1cdbad403f1e9e35f1197482e
 SHA512:
-  metadata.gz: 7236230c824fe40288d3ae3bf972249c056a111789f03db775adecc452b9bdc9d44a92a31fb9adc21c12769cdecdc018d0a1949d6cf9526b0179ad70dbecb18d
-  data.tar.gz: cd3d939196c54291544192b8e968499f9297947c5526d26ce5dd817c36169c0cd9d6c808d160d3bb6bb543979cff836b68271f24c7edbcd09abd49a6a7f0423a
+  metadata.gz: afe31bd9643682f6135d20b25f7d4155e266fd7dee9b4293d1d98c090217f90f6250935c93fb7ffbca154808bc26930c770ee56de33cba4e6c4e1245b7a9629c
+  data.tar.gz: 85bf7c3eb4a28549bff99c8a7c5d98495a0104abcbef4b8af1fed83679dd6ac284be03250a323473d8cd869be5d2792bf3aa2ebcb0bd7f9f3230b2d1b5db0fbf

data/lib/raddocs.rb

@@ -2,6 +2,7 @@ Encoding.default_external = Encoding::UTF_8
 
 require 'sinatra/base'
 require 'json'
+require 'yaml'
 
 require 'raddocs/configuration'
 require 'raddocs/app'

data/lib/raddocs/app.rb

@@ -1,3 +1,20 @@
+# Load the constant
+module Raddocs
+  class App < Sinatra::Base
+    class << self
+      attr_accessor :markdown
+    end
+  end
+end
+
+begin
+  require 'kramdown'
+
+  Raddocs::App.markdown = true
+rescue LoadError
+  # do nothing, we won't load markdown files
+end
+
 module Raddocs
   # Sinatra app that serves all documentation
   class App < Sinatra::Base
@@ -22,6 +39,13 @@ module Raddocs
       File.read(file)
     end
 
+    if markdown
+      get "/guides/*" do
+        file = "#{guides_dir}/#{params[:splat][0]}.md"
+        erb :guide, locals: { guide: File.read(file) }, layout: false
+      end
+    end
+
     # Catch all for example pages.
     # Loads files from the docs dir and appends '.json'.
     #
@@ -87,6 +111,16 @@ module Raddocs
       def docs_dir
         Raddocs.configuration.docs_dir
       end
+
+      def guides
+        YAML.load(File.read(File.join(guides_dir, "guides.yml"))).map do |guide_hash|
+          Guide.new(guide_hash)
+        end
+      end
+
+      def guides_dir
+        Raddocs.configuration.guides_dir
+      end
     end
   end
 end

data/lib/raddocs/configuration.rb

@@ -29,6 +29,10 @@ module Raddocs
     # @return [String] defaults to 'doc/api'
     add_setting :docs_dir, :default => "doc/api"
 
+    # @!attribute guides_dir
+    # @return [String] defaults to 'doc/guides'
+    add_setting :guides_dir, :default => "doc/guides"
+
     # @!attribute docs_mime_type
     # @return [Regexp] defaults to Regexp.new("text/docs\+plain")
     add_setting :docs_mime_type, :default => /text\/docs\+plain/

data/lib/raddocs/models.rb

@@ -62,6 +62,21 @@ module Raddocs
     end
   end
 
+  # Guide page model
+  class Guide
+    attr_reader :title
+
+    def initialize(attributes)
+      @title = attributes.fetch("title")
+      @file = attributes.fetch("file")
+    end
+
+    def href
+      filename = @file.gsub(".md", "")
+      "guides/#{filename}"
+    end
+  end
+
   # An example's parameters, requires a class because the table can display unknown columns
   class Parameters
     attr_reader :extra_keys, :params
@@ -258,6 +273,11 @@ module Raddocs
       !@request_body.nil?
     end
 
+    # @return [Boolean] true if request headers are present
+    def request_headers?
+      request_headers.length > 0
+    end
+
     # Request headers must be set
     # @return [String] Content type of the request
     def request_content_type
@@ -286,6 +306,11 @@ module Raddocs
       !@response_body.nil?
     end
 
+    # @return [Boolean] true if response headers are present
+    def response_headers?
+      response_headers.length > 0
+    end
+
     # Response headers must be set
     # @return [String] Content type of the response
     def response_content_type

data/lib/views/example.haml

@@ -1,137 +1,144 @@
-:javascript
-  function mirror(textarea, contentType, options) {
-    $textarea = $(textarea);
-    if ($textarea.val() != '') {
-      if(contentType.indexOf('json') >= 0) {
-        $textarea.val(JSON.stringify(JSON.parse($textarea.val()), undefined, 2));
-        options.json = true;
-        options.mode = 'javascript';
-      } else if (contentType.indexOf('javascript') >= 0) {
-        options.mode = 'javascript';
-      } else if (contentType.indexOf('xml') >= 0) {
-        options.mode = 'xml';
-      } else {
-        options.mode = 'htmlmixed';
-      }
-    }
-    return CodeMirror.fromTextArea(textarea, options);
-  };
-
-  $(function(){
-    $(".request .body .content").each(function(i, el) {
-      el = $(el);
-      mirror(el.find("textarea")[0], el.data("content-type"), { "readOnly": true, "lineNumbers": true });
-    });
-  });
-
-.nav-bar
-  = link_to "« Back to Index", "/"
-
-%h1== #{example.resource} API
-.article
-  %h2= example.description
-
-  - if example.explanation?
-    %p.explanation
-      = example.explanation
-
-  - if example.parameters.present?
-    %h3 Parameters
-    %table.parameters
-      %thead
-        %tr
-          %th Name
-          %th Description
-          - example.parameters.extra_keys.each do |key|
-            %th= key
-      %tbody
-        - example.parameters.params.each do |param|
-          %tr.parameter
-            %td{:class => ("required" if param.required?)}
-              - if param.scope?
-                %span.name #{param.scope}[#{param.name}]
-              - else
-                %span.name= param.name
-            %td
-              %span.description= param.description
-            - example.parameters.extra_keys.each do |key|
-              %td
-                %span.extras= param[key]
-
-  - if example.response_fields.present?
-    %h3 Response Fields
-    %table.response-fields
-      %thead
-        %tr
-          %th Name
-          %th Description
-          - example.response_fields.extra_keys.each do |key|
-            %th= key
-      %tbody
-        - example.response_fields.fields.each do |field|
-          %tr.response-field
-            %td
-              - if field.scope?
-                %span.name #{field.scope}[#{field.name}]
-              - else
-                %span.name= field.name
-            %td
-              %span.description= field.description
-            - example.response_fields.extra_keys.each do |key|
-              %td
-                %span.extras= field[key]
-
-  - example.requests.each_with_index do |request, index|
-    .request{ :id => "request-#{index}" }
-      %h3 Request
-
-      %section.headers
-        %h4 Headers
-        %pre.headers
-          :preserve
-            #{request.request_headers}
-
-      %section.route
-        %h4 Route
-        %pre.route.highlight== #{request.request_method} #{request.request_path}
-
-      - if request.request_query_parameters?
-        %section.query-parameters
-          %h4 Query Parameters
-          %pre.query-parameters.highlight
-            = request.request_query_parameters
-
-      - if request.request_body?
-        %section.body
-          %h4 Body
-          .content{ "data-content-type" => request.request_content_type }
-            %textarea
-              :preserve
-                #{request.request_body}
-
-      - if request.curl?
-        %section.curl
-          %h4 cURL
-          %pre= request.curl
-
-      - if request.response?
-        .response
-          %h3 Response
-
-          %section.headers
-            %h4 Headers
-            %pre.headers
-              :preserve
-                #{request.response_headers}
-
-          %section.status
-            %h4 Status
-            %pre.status= request.response_status
-
-          - if request.response_body?
+.row-fluid
+  .span4.sidebar
+    = haml :nav, locals: { index: index, api_name: api_name }
+
+  .span10.main
+    :javascript
+      function mirror(textarea, contentType, options) {
+        $textarea = $(textarea);
+        if ($textarea.val() != '') {
+          if(contentType.indexOf('json') >= 0) {
+            $textarea.val(JSON.stringify(JSON.parse($textarea.val()), undefined, 2));
+            options.json = true;
+            options.mode = 'javascript';
+          } else if (contentType.indexOf('javascript') >= 0) {
+            options.mode = 'javascript';
+          } else if (contentType.indexOf('xml') >= 0) {
+            options.mode = 'xml';
+          } else {
+            options.mode = 'htmlmixed';
+          }
+        }
+        return CodeMirror.fromTextArea(textarea, options);
+      };
+
+      $(function(){
+        $(".request .body .content").each(function(i, el) {
+          el = $(el);
+          mirror(el.find("textarea")[0], el.data("content-type"), { "readOnly": true, "lineNumbers": true });
+        });
+      });
+
+    .nav-bar
+      = link_to "« Back to Index", "/"
+
+    %h1== #{example.resource} API
+    .article
+      %h2= example.description
+
+      - if example.explanation?
+        %p.explanation
+          = example.explanation
+
+      - if example.parameters.present?
+        %h3 Parameters
+        %table.parameters
+          %thead
+            %tr
+              %th Name
+              %th Description
+              - example.parameters.extra_keys.each do |key|
+                %th= key
+          %tbody
+            - example.parameters.params.each do |param|
+              %tr.parameter
+                %td{:class => ("required" if param.required?)}
+                  - if param.scope?
+                    %span.name #{param.scope}[#{param.name}]
+                  - else
+                    %span.name= param.name
+                %td
+                  %span.description= param.description
+                - example.parameters.extra_keys.each do |key|
+                  %td
+                    %span.extras= param[key]
+
+      - if example.response_fields.present?
+        %h3 Response Fields
+        %table.response-fields
+          %thead
+            %tr
+              %th Name
+              %th Description
+              - example.response_fields.extra_keys.each do |key|
+                %th= key
+          %tbody
+            - example.response_fields.fields.each do |field|
+              %tr.response-field
+                %td
+                  - if field.scope?
+                    %span.name #{field.scope}[#{field.name}]
+                  - else
+                    %span.name= field.name
+                %td
+                  %span.description= field.description
+                - example.response_fields.extra_keys.each do |key|
+                  %td
+                    %span.extras= field[key]
+
+      - example.requests.each_with_index do |request, index|
+        .request{ :id => "request-#{index}" }
+          %h3 Request
+
+          - if request.response_headers?
+            %section.headers
+              %h4 Headers
+              %pre.headers
+                :preserve
+                  #{request.request_headers}
+
+          %section.route
+            %h4 Route
+            %pre.route.highlight== #{request.request_method} #{request.request_path}
+
+          - if request.request_query_parameters?
+            %section.query-parameters
+              %h4 Query Parameters
+              %pre.query-parameters.highlight
+                = request.request_query_parameters
+
+          - if request.request_body?
             %section.body
               %h4 Body
-              .content{ "data-content-type" => request.response_content_type }
+              .content{ "data-content-type" => request.request_content_type }
                 %textarea
                   :preserve
-                    #{request.response_body}
+                    #{request.request_body}
+
+          - if request.curl?
+            %section.curl
+              %h4 cURL
+              %pre= request.curl
+
+          - if request.response?
+            .response
+              %h3 Response
+
+              - if request.response_headers?
+                %section.headers
+                  %h4 Headers
+                  %pre.headers
+                    :preserve
+                      #{request.response_headers}
+
+              %section.status
+                %h4 Status
+                %pre.status= request.response_status
+
+              - if request.response_body?
+                %section.body
+                  %h4 Body
+                  .content{ "data-content-type" => request.response_content_type }
+                    %textarea
+                      :preserve
+                        #{request.response_body}

data/lib/views/guide.erb

@@ -0,0 +1,44 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <title><%= api_name %></title>
+    <% css_files.each do |file| %>
+      <link rel="stylesheet" href="<%= file %>" />
+    <% end %>
+
+    <script src="#{url_location}/js/jquery-1-7-2.js"></script>
+    <script src="#{url_location}/js/codemirror.js"></script>
+    <script src="#{url_location}/js/mode/css/css.js"></script>
+    <script src="#{url_location}/js/mode/htmlmixed/htmlmixed.js"></script>
+    <script src="#{url_location}/js/mode/javascript/javascript.js"></script>
+    <script src="#{url_location}/js/mode/xml/xml.js"></script>
+
+    <style>
+      td.required .name:after {
+        float: right;
+        content: "required";
+        font-weight: normal;
+        color: #F08080;
+      }
+
+      p {
+        padding: 15px;
+        font-size: 130%;
+      }
+
+      nav {
+        margin-bottom: 15px;
+      }
+    </style>
+  </head>
+  <body>
+
+  <div class="container">
+    <nav>
+      <%= link_to "&laquo; Back to Index", "/" %>
+    </nav>
+
+<%= Kramdown::Document.new(guide, input: "GFM", syntax_highlighter_opts: { line_numbers: false }).to_html %>
+  </div>
+  </body>
+</html>

data/lib/views/index.haml

@@ -1,5 +1,11 @@
 %h1= api_name
 
+%h2 Guides
+%ul.guides
+  - guides.each do |guide|
+    %li.guide
+      = link_to guide.title, "/#{guide.href}"
+
 - index.resources.each do |resource|
   .resource
     %h2= resource.name

data/lib/views/layout.haml

@@ -2,14 +2,17 @@
 %html
   %head
     %title= api_name
+
     - css_files.each do |file|
       %link{:rel => "stylesheet", :href => file}
+
     %script(src="#{url_location}/js/jquery-1-7-2.js")
     %script(src="#{url_location}/js/codemirror.js")
     %script(src="#{url_location}/js/mode/css/css.js")
     %script(src="#{url_location}/js/mode/htmlmixed/htmlmixed.js")
     %script(src="#{url_location}/js/mode/javascript/javascript.js")
     %script(src="#{url_location}/js/mode/xml/xml.js")
+
     :css
       td.required .name:after {
         float: right;
@@ -22,10 +25,7 @@
         padding: 15px;
         font-size: 130%;
       }
+
   %body
     .container
-      .row-fluid
-        .span4.sidebar
-          = haml :nav, locals: { index: index, api_name: api_name }
-        .span8.main
-          = yield
+      = yield

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: raddocs
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Eric Oestrich
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-08-11 00:00:00.000000000 Z
+date: 2016-03-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: sinatra
@@ -17,9 +17,6 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.3'
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 1.3.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -27,9 +24,6 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.3'
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 1.3.0
 - !ruby/object:Gem::Dependency
   name: haml
   requirement: !ruby/object:Gem::Requirement
@@ -37,9 +31,6 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '4.0'
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 4.0.4
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -47,9 +38,6 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '4.0'
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 4.0.4
 - !ruby/object:Gem::Dependency
   name: json
   requirement: !ruby/object:Gem::Requirement
@@ -57,9 +45,6 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.8'
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 1.8.1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -67,9 +52,6 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.8'
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 1.8.1
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -126,6 +108,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: kramdown
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Browse documentation generated by the rspec_api_documentation gem
 email:
 - eric@oestrich.org
@@ -148,6 +144,7 @@ files:
 - lib/raddocs/middleware.rb
 - lib/raddocs/models.rb
 - lib/views/example.haml
+- lib/views/guide.erb
 - lib/views/index.haml
 - lib/views/layout.haml
 - lib/views/nav.haml
@@ -171,7 +168,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: 1.3.6
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.2.2
+rubygems_version: 2.5.1
 signing_key: 
 specification_version: 4
 summary: rspec_api_documentation browser