proscribe 0.0.1

data/HISTORY.md

@@ -0,0 +1,4 @@
+v0.0.1 - Jul 24, 2011
+---------------------
+
+Initial.

data/README.md

@@ -0,0 +1,7 @@
+# ProScribe
+#### Source documentation tool
+
+    $ gem install proscribe
+    $ proscribe
+
+See the source for info on how to use it.

data/bin/proscribe

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+
+require File.expand_path('../../lib/proscribe', __FILE__)
+
+ProScribe::CLI.run!

data/data/default/Gemfile

@@ -0,0 +1,5 @@
+source :rubygems
+
+gem "proton", "~> 0.3.2"
+gem "rack-cache", "~> 1.0.0"
+gem "rdiscount"

data/data/default/Gemfile.lock

@@ -0,0 +1,43 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    RedCloth (4.2.7)
+    chunky_png (1.2.0)
+    compass (0.11.5)
+      chunky_png (~> 1.2)
+      fssm (>= 0.2.7)
+      sass (~> 3.1)
+    cuba (2.0.0)
+      rack (~> 1.2)
+      tilt (~> 1.2)
+    fssm (0.2.7)
+    haml (3.1.2)
+    hashie (1.0.0)
+    maruku (0.6.0)
+      syntax (>= 1.0.0)
+    proton (0.3.3)
+      RedCloth (~> 4.2.3)
+      compass (~> 0.11.1)
+      cuba (~> 2.0.0)
+      haml (~> 3.1.1)
+      hashie (~> 1.0.0)
+      maruku (~> 0.6.0)
+      sass (~> 3.1.1)
+      shake (~> 0.1)
+      tilt (~> 1.2.2)
+    rack (1.3.0)
+    rack-cache (1.0.2)
+      rack (>= 0.4)
+    rdiscount (1.6.8)
+    sass (3.1.4)
+    shake (0.1.2)
+    syntax (1.0.0)
+    tilt (1.2.2)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  proton (~> 0.3.2)
+  rack-cache (~> 1.0.0)
+  rdiscount

data/data/default/Protonfile

@@ -0,0 +1,14 @@
+hyde_requirement: 0.2
+extensions_path: _extensions
+layouts_path:    _layouts
+partials_path:   _layouts
+
+tilt_options:
+  haml:
+    ugly: true
+
+# Custom stuff
+extractor:
+  files:
+    - source: ../lib/**/*.rb
+      target: api/

data/data/default/_extensions/manual/lib/cli.rb

@@ -0,0 +1,18 @@
+class Proton::CLI
+  task :update do
+    require File.expand_path('../extractor', __FILE__)
+
+    Dir.chdir(Hyde.project.root) {
+      Proton.project.config.extractor.files.each { |group|
+        FileUtils.rm_rf group.target
+
+        ex = Extractor.new Dir[group.source]
+
+        ex.write!(group.target) { |b| puts "   update  *  #{File.join(group.target, b.file)}" }
+      }
+    }
+  end
+
+  task.description = "Extracts inline documentation."
+end
+

data/data/default/_extensions/manual/lib/extractor.rb

@@ -0,0 +1,206 @@
+#!/usr/bin/env ruby
+
+require 'ostruct'
+require 'fileutils'
+
+# Extracts comments from list of files.
+# Gets the ones with comment blocks starting with `[...]`
+#
+# == Common usage
+#
+#   ex = Extractor.new('.')
+#   ex.blocks
+#
+#   ex.blocks.map! { |b| b.file = "file: #{b.file}" }
+#
+#   ex.write!('manual/')       # Writes to manual/
+#
+class Extractor
+  def initialize(files, options={})
+    @files = files
+  end
+
+  def write!(output_path = '.', &blk)
+    blocks.each { |block|
+      path = File.join(output_path, block.file)
+      FileUtils.mkdir_p File.dirname(path)
+      File.open(path, 'w') { |f| f.write block.body }
+      yield block  if block_given?
+    }
+  end
+
+  # Returns an array of Extractor::Blocks.
+  def blocks
+    @blocks ||= begin
+      @files.map { |file|
+        if File.file?(file)
+          input = File.read(file)
+          get_blocks input
+        end
+      }.compact.flatten
+    end
+  end
+
+private
+  # Returns blocks that match a blah.
+  def get_blocks(str)
+    arr = get_comment_blocks(str)
+    arr.map { |block|
+      re = /^([A-Za-z ]*?): (.*?)(?: \((.*?)\))?$/
+
+      if block.last =~ re
+        Extractor::Block.new \
+          :type => $1,
+          :title => $2,
+          :parent => $3,
+          :body => (block[0..-2].join("\n") + "\n")
+      elsif block.first =~ re
+        Extractor::Block.new \
+          :type => $1,
+          :title => $2,
+          :parent => $3,
+          :body => (block[1..-1].join("\n") + "\n")
+      end
+    }.compact
+  end
+
+  # Returns contiguous comment blocks.
+  def get_comment_blocks(str)
+    chunks = Array.new
+    i = 0
+
+    str.split("\n").each { |s|
+      if s =~ /^\s*(?:\/\/\/?|##?) ?(.*)$/
+        chunks[i] ||= Array.new
+        chunks[i] << $1
+      else
+        i += 1  if chunks[i]
+      end
+    }
+
+    chunks
+  end
+end
+
+class Extractor::Block
+  attr_accessor :body
+  attr_accessor :file
+
+  def initialize(options)
+    title  = options[:title]
+    parent = options[:parent]
+    body   = options[:body]
+    type   = options[:type].downcase
+
+    file = to_filename(title, parent)
+    brief, *body = body.split("\n\n")
+    body = "#{body.join("\n\n")}"
+
+    heading = "title: #{title}\npage_type: #{type}\nbrief: #{brief}\n"
+    heading += "--\n"
+
+    @file = file
+    body  = Tilt.new(".md") { body }.render
+    body  = fix_links(body, from: file)
+    @body = heading + body
+  end
+
+private
+  def fix_links(str, options={})
+    from = ("/" + options[:from].to_s).squeeze('/')
+    depth = from.to_s.count('/')
+    indent = (depth > 1 ? '../'*(depth-1) : './')[0..-2]
+
+    # First pass: {Helpers::content_for} to become links
+    str = str.gsub(/{([^}]*?)}/) { |s|
+      s = s.gsub(/{|}/, '')
+
+      m = s.match(/^(.*?)[:\.]+([A-Za-z_\(\)\!\?]+)$/)
+      if m
+        name, context = $2, $1
+      else
+        name, context = s, nil
+      end
+
+      s = "<a href='/#{to_filename(s, '', :ext => '.html')}'>#{name}</a>"
+      s += " <span class='context'>(#{context})</span>"  if context
+      s
+    }
+
+    # Second pass: relativize
+    re = /href=['"](\/(?:.*?))['"]/
+    str.gsub(re) { |s|
+      url = s.match(re) && $1
+      url = "#{indent}/#{url}".squeeze('/')
+      "href=#{url.inspect}"
+    }
+  end
+
+  def to_filename(title, parent='', options={})
+    extension = options[:ext] || '.erb'
+    pathify = lambda { |s|
+      s.to_s.scan(/[A-Za-z0-9_\!\?]+/).map { |chunk|
+        chunk = chunk.gsub('?', '_question')
+        chunk = chunk.gsub('!', '_bang')
+
+        if chunk[0].upcase == chunk[0]
+          chunk
+        else
+          "#{chunk}_"
+        end
+      }.join("/")
+    }
+
+    pathify["#{parent}/#{title}"] + extension
+  end
+end
+
+module Extractor::Command
+  module Params
+    def extract(what)
+      i = index(what) and slice!(i, 2)[1]
+    end
+
+    def extract_all(what)
+      re = Array.new
+      while true
+        x = extract(what) or return re
+        re << x
+      end
+    end
+  end
+
+  def self.show_usage
+    puts "Usage: #{$0} <path> [-o <output_path>] [-i <ignore_spec>]"
+    puts "  Extracts documentation comments from files in <path>, and places"
+    puts "  them in <output_path>."
+    puts ""
+    puts "Example:"
+    puts "  #{$0} **/*.rb -o manual/"
+    puts ""
+  end
+
+  def self.run!
+    return show_usage  if ARGV.empty?
+
+    ARGV.extend Params
+
+    glob = lambda { |s| Dir["#{s}/**/*"] + Dir[s] }
+
+    output = ARGV.extract('--output') || ARGV.extract('-o') || '.'
+    ignore = ARGV.extract_all('-i') + ARGV.extract_all('--ignore')
+
+    files  = ARGV.map { |s| glob[s] }.flatten
+    files  = Dir["**/*"]  if ARGV.empty?
+
+    files -= ignore.map { |s| glob[s] }.flatten
+
+    ex = Extractor.new(files)
+    ex.blocks.map { |b| b.file }
+    ex.write!(output) { |blk|
+      puts "* #{blk.file}"
+    }
+  end
+end
+
+Extractor::Command.run!  if $0 == __FILE__

data/data/default/_extensions/manual/lib/helpers.rb

@@ -0,0 +1,32 @@
+module Hyde::Helpers
+  def page_children(page)
+    children = page.children
+    of_type  = lambda { |str| children.select { |p| p.html? && p.meta.page_type == str } }
+
+    children.
+      select { |p| p.html? }.
+      group_by { |p|
+        type = p.meta.page_type
+        type.nil? ? nil : Inflector[type].pluralize.to_sym
+      }
+  end
+end
+
+# Inflector['hello'].pluralize
+class Inflector < String
+  def self.[](str)
+    new str.to_s
+  end
+
+  def pluralize
+    if self[-1] == 's'
+      "#{self}es"
+    else
+      "#{self}s"
+    end
+  end
+
+  def sentencize
+    self.gsub('_', ' ').capitalize
+  end
+end

data/data/default/_extensions/manual/manual.rb

@@ -0,0 +1,2 @@
+require File.expand_path('../lib/cli', __FILE__)
+require File.expand_path('../lib/helpers', __FILE__)

data/data/default/_layouts/_nav.haml

@@ -0,0 +1,8 @@
+- is_active = from == p
+- if p.html?
+  %li
+    %a{href: rel(p.path), class: ("active" if is_active)}= p
+  %ul{class: "level-#{level}"}
+    - p.children.each do |pp|
+      != partial :'_nav', from: from, p: pp, level: level+1
+

data/data/default/_layouts/default.haml

@@ -0,0 +1,123 @@
+!!!
+%html
+  %head
+    %title= page.title
+
+    %meta(charset='UTF-8')
+    -# Use the latest IE engine, or Chrome frame.
+    %meta(http-equiv='X-UA-Compatible' content='IE=edge,chrome=1')
+
+    -# Mobile viewport optimization. j.mp/bplateviewport
+    %meta(name='viewport' content='width=device-width, initial-scale=1.0')
+
+    -# Standard SEO meta
+    - if page.meta.keywords
+      %meta{:name => 'keywords', :content => page.meta.keywords}
+    - if page.meta.description
+      %meta{:name => 'description', :content => page.meta.description}
+
+    %link{:rel => 'stylesheet', :href => rel('/style.css')+"?#{File.mtime(Proton::Page['/style.css'].file).to_i}"}
+
+  %body
+    #top
+      %a#logo{href: rel('/')}
+        = Hyde::Page['/'].title
+
+    #area
+      #content
+        %div.c
+          #crumbs
+            - page.breadcrumbs[0..-2].each do |p|
+              %a{href: rel(p.path)}= p
+              %span.gt!= "→"
+
+            %strong= page
+
+          %hgroup
+            - if page.meta.layout
+              %p.type= page.meta.layout.capitalize
+            %h1= page.title
+            - if page.meta.brief
+              %h5= page.meta.brief
+
+          .content
+            != yield
+
+            - groups = page_children(page)
+            - groups.each do |type, children|
+              %h3= type.to_s.gsub('_', ' ').capitalize
+
+              %ul.section
+                - children.each do |method|
+                  %li
+                    %a{href: rel(method.path)}= method.title
+                    - unless method.meta.brief.to_s.empty?
+                      %span.brief= method.meta.brief
+
+        %nav#nav
+          - parent   = (page.children.any? ? page : (page.parent || page))
+          - children = parent.children.select { |p| p.html? }
+          - groups   = children.group_by { |p| p.meta.page_type }
+
+          - if parent && !parent.root?
+            %nav.parents
+              %ul
+                - parent.breadcrumbs.each do |pp|
+                  %li
+                    %a{href: rel(pp.path), class: ('active' if pp.path == page.path)}
+                      - unless pp.path == page.path
+                        %span.back!= "‹"
+
+                      %em= pp.meta.page_type
+                      = pp
+
+          - if groups.any?
+            - groups.each do |name, pages|
+              - name = name ? Inflector[name].pluralize.capitalize : parent.to_s
+              %nav
+                - if name
+                  %h4= name
+                %ul
+                  - pages.each do |pp|
+                    %li
+                      - classes = []
+                      - classes << 'active'  if pp.path == page.path
+                      - classes << 'more'    if pp.children.any?
+
+                      %a{href: rel(pp.path), class: classes.join(' ')}
+                        = pp
+
+
+    %script{src: 'http://cachedcommons.org/cache/prettify/1.0.0/javascripts/prettify-min.js', type: 'text/javascript'}
+    %script{src: 'http://cdnjs.cloudflare.com/ajax/libs/jquery/1.6.2/jquery.min.js', type: 'text/javascript'}
+    :javascript
+      $(function () {
+        $("pre").each(function() {
+          var r = /\[(.*?)\s*\((.*?)\)\]\n*/;
+          var m = $(this).text().match(r);
+
+          $(this).addClass('prettyprint');
+
+          if (m) {
+            var file = m[1];
+            var type = m[2];
+            $(this).addClass('lang-'+type);
+
+            if (file.length) {
+              $(this).addClass('has-caption');
+              $(this).prepend($("<h5 class='caption'>").text(file));
+            }
+
+            $(this).html($(this).html().replace(r, ''));
+          }
+
+          if ($(this).text().match(/^\s*([a-zA-Z_~\/]*)\$ /)) {
+            $(this).addClass('terminal');
+            $(this).removeClass('prettyprint');
+            $(this).html($(this).html().replace(/([a-zA-Z_~\/]*\$ )(.*?)[\r\n$]/g, "<strong><em>$1</em>$2</strong>\n"));
+          }
+        });
+
+        prettyPrint();
+      });
+