emmett 0.0.1

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in emmett.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Darcy Laycock
+
+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:
+
+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.

data/README.md

@@ -0,0 +1,74 @@
+# Emmett
+
+Emmett is a tool named after Dr Emmett Brown from Back to the Future.
+
+It's purpose is simple - given an index page and a bunch of API documents, it'll take
+them and generate a nice, usable website people can use to consume the documentation.
+
+It doesn't automate the docs or the like - it just does the simplest thing possible.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'emmett'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install emmett
+
+## Usage
+
+Emmett is primarily intended to be used as a rake task.
+
+### Emmett + Rails
+
+Want to generate the documentation directly in your application?
+
+To configure it, the following options are available - simply put them in
+`config/application.rb` and change them as fit:
+
+```ruby
+config.emmett.name        = "Your App"
+config.emmett.index_page  = "doc/api.md" # Relative to doc/
+config.emmett.section_dir = "doc/api" # Relative to doc/
+config.emmett.output_dir  = "doc/generated-api"
+config.emmett.template    = :default
+```
+
+It will use sane defaults (all being the same as above except the name, which is
+the rails root dir titleize. I do suggest changing this). In Rails, it will
+be available via `rake doc:api`.
+
+### Emmett on it's own.
+
+Likewise, you can use emmett inside any application thanks to the Rake Task.
+
+In your Rakefile, simply add:
+
+```ruby
+require 'emmett/rake_task'
+
+Emmett::RakeTask.new :docs do |t|
+  t.name        = "Your App"
+  t.index_page  = "api.md"
+  t.section_dir = "api"
+  t.output_dir  = "output"
+  t.template    = :default
+end
+```
+
+Like the rails version, this will use the values above as output,
+with the name being based on the current directory name.
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+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

data/Rakefile

@@ -0,0 +1,2 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"

data/emmett.gemspec

@@ -0,0 +1,27 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/emmett/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.authors       = ["Darcy Laycock"]
+  gem.email         = ["darcy@filtersquad.com"]
+  gem.description   = %q{Tools to make building API docs simpler.}
+  gem.summary       = %q{Tools to make building API docs simpler.}
+  gem.homepage      = ""
+
+  gem.files         = `git ls-files`.split($\)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.name          = "emmett"
+  gem.require_paths = ["lib"]
+  gem.version       = Emmett::VERSION
+
+  gem.add_dependency 'github-markdown'
+  gem.add_dependency 'github-markup'
+  gem.add_dependency 'nokogiri'
+  gem.add_dependency 'pygments.rb'
+  gem.add_dependency 'handlebars'
+  gem.add_dependency 'rake'
+  gem.add_dependency 'oj'
+  gem.add_dependency 'http_parser.rb'
+
+end

data/lib/emmett/configuration.rb

@@ -0,0 +1,30 @@
+require 'emmett/template'
+
+module Emmett
+  class Configuration
+
+    class Error < StandardError; end
+
+    attr_accessor :name, :template, :index_page, :section_dir, :output_dir
+
+    def verify!
+      errors = []
+      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)
+      errors << "The section_dir directory must exist" unless section_dir && File.directory?(section_dir)
+      errors << "The output_dir must be set" unless output_dir
+      errors << "The specified template does not exist" unless to_template
+      if errors.any?
+        message = "Your configuration is invalid:\n"
+        errors.each { |e| message << "* #{e}\n" }
+        raise Error.new(message)
+      end
+    end
+
+    def to_template
+      @template_instance ||= Template[template]
+    end
+
+  end
+end

data/lib/emmett/document.rb

@@ -0,0 +1,126 @@
+require 'pygments'
+require 'github/markdown'
+require 'github/markup'
+require 'nokogiri'
+
+require 'emmett/http_request_processor'
+
+module Emmett
+  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 short_name
+      @short_name ||= begin
+        if type == :index
+          "index"
+        else
+          File.basename(file_name).split(".")[0..-2].join(".")
+        end
+      end
+    end
+
+    def document
+      @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
+    end
+
+    def highlighted_html
+      @highlighted_html ||= begin
+        doc = document.clone
+        doc.css('pre[lang]').each do |block|
+          inner                = block.at_css('code')
+          highlighted          = Pygments.highlight(inner.inner_html, options: {encoding: 'utf-8'}, lexer: block[:lang])
+          highlighted_fragment = Nokogiri::HTML::DocumentFragment.parse highlighted
+          highlighted_fragment["data-code-lang"] = block[:lang]
+          block.replace highlighted_fragment
+        end
+
+        mapping = section_mapping
+        doc.css('h2').each do |header|
+          if (identifier = mapping[header.text])
+            header[:id] = identifier
+          end
+        end
+
+        unless short_name == 'index'
+          # Now, insert an endpoints content before the start of it.
+          toc = Nokogiri::HTML::DocumentFragment.parse toc_html
+          doc.at_css('h2').add_previous_sibling toc
+        end
+
+        doc.css('body').inner_html
+      end
+    end
+
+    def toc_html
+      [].tap do |html|
+        html << "<h2>Endpoints</h2>"
+        html << "<ul id='endpoints'>"
+
+        section_mapping.each_pair do |section, slug|
+          html << "<li><a href='##{slug}'>#{section}</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
+
+    def code_blocks
+      @code_blocks ||= begin
+        last_header = nil
+        blocks      = []
+        document.css('h2, pre[lang]').each do |d|
+          if d.name == 'h2'
+            last_header = d.text
+          else
+            blocks << [d[:lang], d.at_css('code').text, last_header]
+          end
+        end
+        blocks
+      end
+    end
+
+    def http_blocks
+      @http_blocks ||= code_blocks.select { |r| r.first == "http" }.map { |r| r[1..-1] }
+    end
+
+    def http_requests
+      @http_requests ||= http_blocks.select do |cb|
+        first_line = cb[0].lines.first.strip
+        first_line =~ /\A[A-Z]+ (\S+) HTTP\/1\.1\Z/
+      end.map { |r| HTTPRequestProcessor.new(*r) }
+    end
+
+    def http_responses
+      @http_responses ||= http_blocks.select do |cb|
+        first_line = cb.lines.first.strip
+        first_line =~ /\AHTTP\/1\.1 (\d+) (\w+)\Z/
+      end
+    end
+
+  end
+end

data/lib/emmett/document_manager.rb

@@ -0,0 +1,89 @@
+require 'emmett/document'
+require 'emmett/renderer'
+
+module Emmett
+  class DocumentManager
+
+    def self.render!(*args)
+      new(*args).render!
+    end
+
+    attr_reader :configuration
+
+    def initialize(configuration)
+      @configuration = configuration
+    end
+
+    def index_document
+      @index_document ||= render_path(configuration.index_page, :index)
+    end
+
+    def inner_documents
+      @inner_documents ||= begin
+        Dir[File.join(configuration.section_dir, "**/*.md")].map do |path|
+          render_path path
+        end
+      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 }
+    end
+
+    def render_index(renderer)
+      render_document renderer, :index, index_document
+    end
+
+    def render_documents(renderer)
+      inner_documents.each do |document|
+        render_document renderer, :section, document
+      end
+    end
+
+    def render(renderer)
+      render_index renderer
+      render_documents renderer
+    end
+
+    def render!
+      Renderer.new(configuration).tap do |renderer|
+        renderer.prepare_output
+        renderer.global_context = {
+          links:     inner_links,
+          site_name: configuration.name
+        }
+        render renderer
+      end
+    end
+
+    def all_urls
+      out = inner_documents.inject({}) do |acc, current|
+        acc[current.title] = current.http_requests.inject({}) do |ia, req|
+          ia[req.section] ||= []
+          ia[req.section] << req.request_line
+          ia
+        end
+        acc
+      end
+    end
+
+    private
+
+    def render_document(renderer, template_name, document, context = {})
+      renderer.render_to document.to_path_name, template_name, context.merge(content: document.highlighted_html)
+    end
+
+    def render_path(path, type = :normal)
+      Document.from_path path, type
+    end
+
+  end
+end

data/lib/emmett/http_request_processor.rb

@@ -0,0 +1,70 @@
+require 'http/parser'
+require 'oj'
+
+module Emmett
+  class HTTPRequestProcessor
+
+    attr_reader :headers, :body, :method, :url, :http_version, :section
+
+    def initialize(request, section)
+      @raw_request = request.gsub(/\r?\n/m, "\r\n")
+      @body        = ""
+      @section     = section
+      parse!
+    end
+
+    def parse!
+      parser = Http::Parser.new
+
+      parser.on_headers_complete = proc do
+        @http_version = parser.http_version
+        @method       = parser.http_method
+        @url          = parser.request_url
+        @headers      = parser.headers
+      end
+
+      parser.on_body = proc do |chunk|
+        # One chunk of the body
+        @body << chunk
+      end
+
+      parser.on_message_complete = proc do |env|
+        @parsed = true
+      end
+
+      @parsed = false
+      parser << @raw_request
+      parser << "\r\n" until @parsed
+    end
+
+    def has_body?
+      @body.strip.length > 0
+    end
+
+    def authenticated?
+      headers['Authorization'] && headers['Authorization'] =~ /bearer/i
+    end
+
+    def request_line
+      "#{method} #{url}"
+    end
+
+    def json?
+      headers['Content-Type'] && headers['Content-Type'].include?("application/json")
+    end
+
+    def has_valid_json?
+      return @has_valid_json if instance_variable_defined?(:@has_valid_json)
+
+      begin
+        Oj.load body
+        @has_valid_json = true
+      rescue SyntaxError
+        @has_valid_json = false
+      end
+
+      @has_valid_json
+    end
+
+  end
+end

data/lib/emmett/railtie.rb

@@ -0,0 +1,22 @@
+require 'emmett/configuration'
+
+module Emmett
+  class Railtie < ::Rails::Railtie
+    R = ::Rails
+
+    config.emmett             = Emmett::Configuration.new
+    config.emmett.name        = File.basename(Dir.pwd).titleize
+    config.emmett.index_page  = "doc/api.md"
+    config.emmett.section_dir = "doc/api"
+    config.emmett.output_dir  = "doc/generated-api"
+    config.emmett.template    = :default
+
+    rake_tasks do
+      require 'emmett/rake_task'
+      namespace :doc do
+        Emmett::RakeTask.new(:api) { |t| t.configuration = Rails.application.config.emmett }
+      end
+    end
+
+  end
+end

data/lib/emmett/rake_task.rb

@@ -0,0 +1,47 @@
+require 'rake'
+require 'rake/tasklib'
+require 'emmett'
+
+module Emmett
+  class RakeTask < ::Rake::TaskLib
+    include ::Rake::DSL if defined?(::Rake::DSL)
+
+    def configuration
+      @configuration ||= build_default_configuration
+    end
+
+    # Proxy each of the configuration options.
+    def name=(value);        configuration.name = value; end
+    def index_page=(value);  configuration.index_page = value; end
+    def section_dir=(value); configuration.section_dir = value; end
+    def output_dir=(value);  configuration.output_dir = value; end
+    def template=(value);    configuration.template = value; end
+
+    attr_accessor :task_name
+    attr_writer   :configuration
+
+    def initialize(*args)
+      @task_name = args.shift || :emmett
+      yield self if block_given?
+      desc "Generates api documentation using emmett" unless ::Rake.application.last_comment
+      task task_name do
+        configuration.verify!
+        Emmett::DocumentManager.render! configuration
+      end
+
+    end
+
+    private
+
+    def build_default_configuration
+      c             = Configuration.new
+      c.name        = File.basename(Dir.pwd)
+      c.index_page  = "api.md"
+      c.section_dir = "api"
+      c.output_dir  = "output"
+      c.template    = :default
+      c
+    end
+
+  end
+end

data/lib/emmett/renderer.rb

@@ -0,0 +1,68 @@
+require 'fileutils'
+require 'handlebars'
+require 'pathname'
+
+module Emmett
+  class Renderer
+
+    attr_reader :handlebars, :global_context, :configuration, :templates
+    attr_writer :global_context
+
+    def initialize(configuration)
+      @configuration  = configuration
+      @templates      = configuration.to_template
+      @handlebars     = Handlebars::Context.new
+      @cache          = {}
+      @global_context = {}
+      configure_handlebars
+    end
+
+    def render(template, context = {})
+      load_template(template).call global_context.merge(context)
+    end
+
+    def render_to(output, name, context = {})
+      out = File.join(output_path, output)
+      File.open(out, 'w+') do |f|
+        f.write render(name, context)
+      end
+    end
+
+    def prepare_output
+      FileUtils.rm_rf   output_path
+      FileUtils.mkdir_p output_path
+      copy_static
+    end
+
+    private
+
+    def output_path
+      @output_path ||= configuration.output_dir
+    end
+
+    def copy_static
+      templates.each_static_file do |file_name, path|
+        destination = File.join(output_path, file_name)
+        FileUtils.mkdir_p File.dirname(destination)
+        FileUtils.cp path, destination
+      end
+    end
+
+    def configure_handlebars
+      handlebars.partial_missing do |name|
+        template = load_template "_#{name}"
+        lambda do |this, context, options|
+          template.call context
+        end
+      end
+    end
+
+    def load_template(name)
+      @cache[name.to_s] ||= begin
+        path = templates.template_file_path("#{name}.handlebars")
+        path && handlebars.compile(File.read(path))
+      end
+    end
+
+  end
+end

data/lib/emmett/template.rb

@@ -0,0 +1,81 @@
+module Emmett
+  class Template
+
+    class Error < StandardError; end
+
+    class << self
+
+      def registry
+        @registry ||= {}
+      end
+
+      def register(name, value)
+        registry[name.to_sym] = value
+      end
+
+      def [](name)
+        registry.fetch(name.to_sym) { raise "Emmett does not know a template by the name '#{name}'" }
+      end
+
+      def add(name, path)
+        new(name, path).tap do |template|
+          template.verify!
+          template.register
+        end
+      end
+
+    end
+
+    attr_reader :name, :root
+
+    def initialize(name, root)
+      @name = name && name.to_sym
+      @root = root.to_s
+    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)
+      if errors.any?
+        message = "The following errors occured trying to add your template:\n"
+        errors.each { |e| message << "* #{message}\n" }
+        raise Error.new(mesage)
+      end
+    end
+
+    def static_path
+      @static_path ||= File.join(root, 'static')
+    end
+
+    def template_path
+      @template_path ||= File.join(root, 'templates')
+    end
+
+    def template_file_path(name)
+      path = File.join(template_path, name)
+      File.exist?(path) ? path : nil
+    end
+
+    def has_template?(name)
+      File.exist?
+    end
+
+    def each_static_file
+      Dir[File.join(static_path, '**/*')].select { |f| File.file?(f) }.each do |file|
+        relative_name = file.gsub(static_path, "")
+        yield relative_name, file
+      end
+    end
+
+    def register
+      self.class.register name, self
+    end
+
+    # Add the default template, located within the gem.
+    add :default, File.expand_path('../../../templates/default', __FILE__)
+
+  end
+end

data/lib/emmett/version.rb

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