emmett 0.0.1 → 0.0.2

data/LICENSE

@@ -1,22 +1,19 @@
-Copyright (c) 2012 Darcy Laycock
+Copyright (c) 2012 Filter Squad
 
-MIT License
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
 
-Permission is hereby granted, free of charge, to any person obtaining
-a copy of this software and associated documentation files (the
-"Software"), to deal in the Software without restriction, including
-without limitation the rights to use, copy, modify, merge, publish,
-distribute, sublicense, and/or sell copies of the Software, and to
-permit persons to whom the Software is furnished to do so, subject to
-the following conditions:
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
 
-The above copyright notice and this permission notice shall be
-included in all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
-EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
-NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
-LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
-OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
-WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -7,6 +7,39 @@ them and generate a nice, usable website people can use to consume the documenta
 
 It doesn't automate the docs or the like - it just does the simplest thing possible.
 
+## Doc Generation
+
+Emmett is simply a pipeline for building documentation. It expects very little, namely:
+
+* There is a specific api index page.
+* There is a directory holding all API section information as markdown files
+* Each page has a h1 with the section name
+* Each page has one or more h2's with an api endpoint described inside a single one.
+
+From this, it will generate compiled HTML from a template (the default is built on bootstrap)
+with:
+
+* Markdown processed much like on GitHub.
+* A nav bar with your api name + drop downs of section titles.
+* An index of endpoints in each section before any of the endpoints are described.
+* An api index on the home page.
+
+It'll automatically use Pygments for code highlighting, so for http examples we encourage the syntax like:
+
+    ```http
+    GET /1/your/endpoint HTTP/1.1
+    Authorization: Bearer TOKEN
+    ``
+
+    ```http
+    HTTP/1.1 200 OK
+    Content-Type: text/plain
+
+    Alrighty then!
+    ```
+
+AKA, Calls described in the form of a simplified request lifecycle.
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -72,3 +105,7 @@ with the name being based on the current directory name.
 3. Commit your changes (`git commit -am 'Added some feature'`)
 4. Push to the branch (`git push origin my-new-feature`)
 5. Create new Pull Request
+
+## License
+
+Emmett is released under the MIT License (see the [license file](https://github.com/filtersquad/emmett/blob/master/LICENSE)) and is copyright Filter Squad, 2012.

data/lib/emmett/configuration.rb

@@ -1,14 +1,21 @@
 require 'emmett/template'
+require 'json'
 
 module Emmett
   class Configuration
 
     class Error < StandardError; end
 
-    attr_accessor :name, :template, :index_page, :section_dir, :output_dir
+    attr_accessor :name, :template, :index_page, :section_dir, :output_dir, :json_path
 
     def verify!
       errors = []
+      if json_path && File.exist?(json_path)
+        title = from_json['title']
+        self.name = title if title
+      else
+        errors << "The json path does not exist (Given #{json_path.inspect})"
+      end
       errors << "You must set the name attribute for emmett" if !name
       errors << "You must set the template attribute for emmett" if !template
       errors << "The index_page file must exist" unless index_page && File.exist?(index_page)
@@ -22,6 +29,10 @@ module Emmett
       end
     end
 
+    def from_json
+      @json_config ||= JSON.parse(File.read(json_path))
+    end
+
     def to_template
       @template_instance ||= Template[template]
     end

data/lib/emmett/document.rb

@@ -6,12 +6,128 @@ require 'nokogiri'
 require 'emmett/http_request_processor'
 
 module Emmett
+
+  def self.normalize_name(text)
+    text.strip.downcase.gsub(/\W+/, '-').gsub(/-+/, '-').gsub(/(^-|-$)/, '')
+  end
+
+  class Section < Struct.new(:name)
+
+    def groups
+      @groups ||= []
+    end
+
+    def groups=(value)
+      @groups = Array value
+    end
+
+    def singular?
+      @groups.one?
+    end
+
+    def ==(other)
+      other.is_a?(self.class) && other.name == name
+    end
+
+    def to_hash
+      {
+        :name     => name,
+        :singular => singular?,
+        :groups   => groups.map(&:to_hash)
+      }.tap do |result|
+        if singular?
+          group = groups.first.to_hash
+          result[:endpoints] = group[:endpoints]
+          result[:url]       = group[:url]
+        end
+      end
+    end
+
+  end
+
+  class Group < Struct.new(:name)
+
+    attr_reader :slug, :document
+
+    def ==(other)
+      other.is_a?(self.class) && other.name == name
+    end
+
+    def initialize(name, document)
+      @slug = Emmett.normalize_name name
+      @document = document
+      super name
+    end
+
+    def to_hash
+      {
+        :name => name,
+        :slug => slug,
+        :endpoints => endpoints.map(&:to_hash),
+        :url       => document.to_path_name
+      }
+    end
+
+    def endpoints
+      @endpoints ||= []
+    end
+
+    def endpoints=(value)
+      @endpoints = Array value
+    end
+
+  end
+
+  class Endpoint < Struct.new(:name)
+
+    def ==(other)
+      other.is_a?(self.class) && other.name == name
+    end
+
+    attr_reader :slug, :document
+
+    def initialize(name, document)
+      @slug = Emmett.normalize_name name
+      @document = document
+      super name
+    end
+
+    def to_hash
+      {
+        :name => name,
+        :slug => slug,
+        :url  => "#{document.to_path_name}##{slug}"
+      }
+    end
+
+  end
+
   class Document < Struct.new(:file_name, :content, :type)
 
     def self.from_path(path, type = :normal)
       Document.new path, GitHub::Markup.render(path, File.read(path)), type
     end
 
+    def group_names
+      @group_name ||= document.css('h1').map(&:text)
+    end
+
+    def endpoint_names
+      @endpoint_names ||= document.css('h2').map(&:text)
+    end
+
+    def groups
+      @groups ||= group_names.map do |name|
+        group = Group.new(name, self)
+        group.endpoints = endpoints
+        group
+      end
+    end
+
+    def endpoints
+      @endpoints ||= endpoint_names.map { |name| Endpoint.new(name, self) }
+    end
+
     def short_name
       @short_name ||= begin
         if type == :index
@@ -26,19 +142,8 @@ module Emmett
       @document ||= Nokogiri::HTML(content)
     end
 
-    def sections
-      @sections ||= document.css('h2').map(&:text)
-    end
-
-    def section_mapping
-      @section_mapping ||= sections.inject({}) do |acc, current|
-        acc[current] = current.strip.downcase.gsub(/\W+/, '-').gsub(/-+/, '-').gsub(/(^-|-$)/, '')
-        acc
-      end
-    end
-
     def title
-      @title ||= document.at_css('h1').text
+      @title ||= group_names.first
     end
 
     def highlighted_html
@@ -52,7 +157,7 @@ module Emmett
           block.replace highlighted_fragment
         end
 
-        mapping = section_mapping
+        mapping = endpoints.inject({}) { |acc, e| acc[e.name] = e.slug; acc }
         doc.css('h2').each do |header|
           if (identifier = mapping[header.text])
             header[:id] = identifier
@@ -74,17 +179,13 @@ module Emmett
         html << "<h2>Endpoints</h2>"
         html << "<ul id='endpoints'>"
 
-        section_mapping.each_pair do |section, slug|
-          html << "<li><a href='##{slug}'>#{section}</a></li>"
+        endpoints.each do |endpoint|
+          html << "<li><a href='##{endpoint.slug}'>#{endpoint.name}</a></li>"
         end
         html << "</ul>"
       end.join("")
     end
 
-    def iterable_section_mapping
-      section_mapping.map { |(n,v)| {name: n, hash: v} }
-    end
-
     def to_path_name
       "#{short_name}.html"
     end
@@ -104,6 +205,8 @@ module Emmett
       end
     end
 
+    # Extra / process HTTP blocks to get extra information.
+
     def http_blocks
       @http_blocks ||= code_blocks.select { |r| r.first == "http" }.map { |r| r[1..-1] }
     end

data/lib/emmett/document_manager.rb

@@ -1,5 +1,6 @@
 require 'emmett/document'
 require 'emmett/renderer'
+require 'set'
 
 module Emmett
   class DocumentManager
@@ -26,16 +27,15 @@ module Emmett
       end
     end
 
-    def inner_links
-      @inner_links ||= inner_documents.map do |doc|
-        {
-          doc:      doc,
-          title:    doc.title,
-          short:    doc.short_name,
-          link:     "./#{doc.short_name}.html",
-          sections: doc.iterable_section_mapping
-        }
-      end.sort_by { |r| r[:title].downcase }
+    def indexed_documents
+      @indexed_documents ||= inner_documents.inject({}) do |acc, document|
+        acc[document.short_name] = document
+        acc
+      end
+    end
+
+    def sections
+      @sections ||= Hash.new.tap { |s| process_sections s }.values
     end
 
     def render_index(renderer)
@@ -49,6 +49,7 @@ module Emmett
     end
 
     def render(renderer)
+      process_sections
       render_index renderer
       render_documents renderer
     end
@@ -56,8 +57,10 @@ module Emmett
     def render!
       Renderer.new(configuration).tap do |renderer|
         renderer.prepare_output
+        all_groups = sections.map(&:groups).flatten.sort_by(&:name).uniq
         renderer.global_context = {
-          links:     inner_links,
+          sections:  sections.map(&:to_hash),
+          groups:    all_groups.map(&:to_hash),
           site_name: configuration.name
         }
         render renderer
@@ -77,6 +80,25 @@ module Emmett
 
     private
 
+    def process_sections(into = {})
+      configuration_sections = Array(configuration.from_json['sections'])
+      seen                   = Set.new
+      configuration_sections.each do |s|
+        name           = s['name']
+        section        = (into[name] ||= Section.new(name))
+        entries        = Array(s['children']).map { |n| indexed_documents[n] }.compact.map(&:groups).flatten.uniq
+        section.groups += entries
+        seen           += entries
+      end
+      missing = (inner_documents.map(&:groups).flatten.uniq - seen.to_a)
+      missing.each do |group|
+        # This document doesn't have a section, so we need to specify it.
+        section         = (into[group.name] ||= Section.new(group.name))
+        section.groups << group
+      end
+      into
+    end
+
     def render_document(renderer, template_name, document, context = {})
       renderer.render_to document.to_path_name, template_name, context.merge(content: document.highlighted_html)
     end

data/lib/emmett/railtie.rb

@@ -9,6 +9,7 @@ module Emmett
     config.emmett.index_page  = "doc/api.md"
     config.emmett.section_dir = "doc/api"
     config.emmett.output_dir  = "doc/generated-api"
+    config.emmett.json_path   = "doc/api.json"
     config.emmett.template    = :default
 
     rake_tasks do

data/lib/emmett/renderer.rb

@@ -59,7 +59,7 @@ module Emmett
 
     def load_template(name)
       @cache[name.to_s] ||= begin
-        path = templates.template_file_path("#{name}.handlebars")
+        path = templates.template_file_path name
         path && handlebars.compile(File.read(path))
       end
     end

data/lib/emmett/template.rb

@@ -1,8 +1,9 @@
 module Emmett
   class Template
-
     class Error < StandardError; end
 
+    REQUIRED_TEMPLATES = %w(index section)
+
     class << self
 
       def registry
@@ -33,16 +34,25 @@ module Emmett
       @root = root.to_s
     end
 
+    def template_format; "handlebars"; end
+
     def verify!
       errors = []
       errors << "Ensure the root directory exists" unless File.directory?(root)
       errors << "Ensure the name is set" unless name
       errors << "Ensure the template has a templates subdirectory" unless File.directory?(template_path)
       errors << "Ensure the template static path is a directory if present" if File.exist?(static_path) && !File.directory?(static_path)
+      errors << "Missing the following files in your template: #{missing_templates.join(", ")}" if missing_templates.any?
       if errors.any?
         message = "The following errors occured trying to add your template:\n"
-        errors.each { |e| message << "* #{message}\n" }
-        raise Error.new(mesage)
+        errors.each { |e| message << "* #{e}\n" }
+        raise Error.new(message)
+      end
+    end
+
+    def missing_templates
+      @missing_templates ||= REQUIRED_TEMPLATES.select do |template|
+        template_file_path(template).nil?
       end
     end
 
@@ -55,7 +65,7 @@ module Emmett
     end
 
     def template_file_path(name)
-      path = File.join(template_path, name)
+      path = File.join(template_path, "#{name}.#{template_format}")
       File.exist?(path) ? path : nil
     end
 

data/lib/emmett/version.rb

@@ -1,3 +1,3 @@
 module Emmett
-  VERSION = "0.0.1"
+  VERSION = "0.0.2"
 end

data/templates/default/static/stylesheets/documentation.css

@@ -135,12 +135,27 @@ footer.footer {
   color: #444;
 }
 
-#document-index .sections li {
+#document-index .endpoints li {
   line-height: 1.8em;
 }
 
-#document-index .sections a {
+#document-index .endpoints a {
   font-size: 1em;
   font-weight: normal;
   color: #666;
+}
+
+#page-navigation .dropdown  .group-subtitle {
+  font-weight: bold;
+}
+
+#page-navigation .dropdown ul.endpoints {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+  color: #333;
+}
+
+#page-navigation .dropdown ul.endpoints li a {
+  padding-left: 25px;
 }

data/templates/default/templates/_endpoints.handlebars

@@ -0,0 +1,3 @@
+{{#endpoints}}
+<li class='endpoints'><a href="{{url}}">{{name}}</a></li>
+{{/endpoints}}

data/templates/default/templates/_navigation.handlebars

@@ -3,16 +3,27 @@
     <div class='container'>
       <a href="./index.html" class="brand">{{site_name}}</a>
       <ul class='nav pull-right'>
-        {{#links}}
-          <li class='dropdown'>
-            <a href='{{link}}' class='dropdown-toggle{{#is_current_doc}} current-document{{/is_current_doc}}' data-toggle='dropdown'>{{title}} <b class="caret"></b></a>
-            <ul class="dropdown-menu">
-              {{#sections}}
-                <li><a href="{{../link}}#{{hash}}">{{name}}</a></li>
-              {{/sections}}
+        {{#sections}}
+        <li class='dropdown'>
+          {{#if singular}}
+            {{#groups}}
+            <a {{#url}}href='{{url}}'{{/url}} class='dropdown-toggle' data-toggle='dropdown'>{{name}} <b class="caret"></b></a>
+            <ul class="dropdown-menu singular endpoints">{{>endpoints}}</ul>
+            {{/groups}}
+          {{/if}}
+          {{#unless singular}}
+            <a class='dropdown-toggle' data-toggle='dropdown'>{{name}} <b class="caret"></b></a>
+            <ul class="dropdown-menu multiple">
+                {{#groups}}
+                  <li class='group'>
+                    <a href='{{url}}' class='group-subtitle'>{{name}}</a>
+                    <ul class='endpoints'>{{>endpoints}}</ul>
+                  </li>
+                {{/groups}}
             </ul>
-          </li>
-        {{/links}}
+          {{/unless}}
+        </li>
+        {{/sections}}
       </ul>
     </div>
   </div>

data/templates/default/templates/index.handlebars

@@ -14,16 +14,12 @@
         <h2>API Index</h2>
         <div id='inner-index'>
           <ul>
-            {{#links}}
+            {{#groups}}
               <li>
-                <h3><a href="{{link}}">{{title}}</a></h4>
-                <ul class="sections">
-                  {{#sections}}
-                    <li><a href="{{../link}}#{{hash}}">{{name}}</a></li>
-                  {{/sections}}
-                </ul>
+                <h3><a href="{{url}}">{{name}}</a></h4>
+                <ul class="endpoints">{{>endpoints}}</ul>
               </li>
-            {{/links}}
+            {{/groups}}
           </ul>
         </div>
       </section>

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: emmett
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-07-06 00:00:00.000000000 Z
+date: 2012-09-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: github-markdown
@@ -169,6 +169,7 @@ files:
 - templates/default/static/javascripts/jquery-1.7.2.min.js
 - templates/default/static/stylesheets/bootstrap.min.css
 - templates/default/static/stylesheets/documentation.css
+- templates/default/templates/_endpoints.handlebars
 - templates/default/templates/_footer.handlebars
 - templates/default/templates/_head.handlebars
 - templates/default/templates/_navigation.handlebars
@@ -186,12 +187,18 @@ required_ruby_version: !ruby/object:Gem::Requirement
   - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
+      segments:
+      - 0
+      hash: 1631976447622256131
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
   - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
+      segments:
+      - 0
+      hash: 1631976447622256131
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.24