rocco 0.1

data/COPYING

@@ -0,0 +1,18 @@
+Copyright (c) 2010 Ryan Tomayko <http://tomayko.com/about>
+
+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 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,8 @@
+# rocco
+
+This is a Ruby port of [Docco](http://jashkenas.github.com/docco/), a
+_quick-and-dirty, hundred-line-long, literate-programming-style
+documentation generator_.
+
+See the [Rocco generated documentation](http://rtomayko.github.com/rocco/)
+for more information.

data/Rakefile

@@ -0,0 +1,59 @@
+require 'rake/testtask'
+task :default => :test
+
+desc 'Run tests (default)'
+Rake::TestTask.new(:test) do |t|
+  t.test_files = FileList['test/*_test.rb']
+  t.ruby_opts = ['-rubygems'] if defined? Gem
+end
+
+# PACKAGING =================================================================
+
+if defined?(Gem)
+  SPEC = eval(File.read('rocco.gemspec'))
+
+  def package(ext='')
+    "pkg/rocco-#{SPEC.version}" + ext
+  end
+
+  desc 'Build packages'
+  task :package => %w[.gem .tar.gz].map {|e| package(e)}
+
+  desc 'Build and install as local gem'
+  task :install => package('.gem') do
+    sh "gem install #{package('.gem')}"
+  end
+
+  directory 'pkg/'
+
+  file package('.gem') => %w[pkg/ rocco.gemspec] + SPEC.files do |f|
+    sh "gem build rocco.gemspec"
+    mv File.basename(f.name), f.name
+  end
+
+  file package('.tar.gz') => %w[pkg/] + SPEC.files do |f|
+    sh "git archive --format=tar HEAD | gzip > #{f.name}"
+  end
+end
+
+# GEMSPEC ===================================================================
+
+file 'rocco.gemspec' => FileList['{lib,test,bin}/**','Rakefile'] do |f|
+  # read version from tilt.rb
+  version = File.read('lib/rocco.rb')[/VERSION = '(.*)'/] && $1
+  # read spec file and split out manifest section
+  spec = File.
+    read(f.name).
+    sub(/s\.version\s*=\s*'.*'/, "s.version = '#{version}'")
+  parts = spec.split("  # = MANIFEST =\n")
+  # determine file list from git ls-files
+  files = `git ls-files`.
+    split("\n").sort.reject{ |file| file =~ /^\./ }.
+    map{ |file| "    #{file}" }.join("\n")
+  # piece file back together and write...
+  parts[1] = "  s.files = %w[\n#{files}\n  ]\n"
+  spec = parts.join("  # = MANIFEST =\n")
+  spec.sub!(/s.date = '.*'/, "s.date = '#{Time.now.strftime("%Y-%m-%d")}'")
+  File.open(f.name, 'w') { |io| io.write(spec) }
+  puts "updated #{f.name}"
+end

data/bin/rocco

@@ -0,0 +1,30 @@
+#!/usr/bin/env ruby
+libdir = File.expand_path('../../lib', __FILE__).sub(/^#{Dir.pwd}\//, '')
+
+begin
+  require 'rdiscount'
+  require 'rocco'
+rescue LoadError
+  case $!.to_s
+  when /rdiscount/
+    if !defined?(Gem)
+      warn "warn: #$!. trying again with rubygems"
+      require 'rubygems'
+      retry
+    end
+  when /rocco/
+    if !$:.include?(libdir)
+      warn "warn: #$!. trying again with #{libdir} on load path"
+      $:.unshift(libdir)
+      retry
+    end
+  end
+  raise
+end
+
+ARGV.each do |filename|
+  rocco = Rocco.new(filename)
+  dest = File.basename(filename, '.rb') + '.html'
+  warn "rocco: #{filename} -> #{dest}"
+  File.open(dest, 'wb') { |fd| fd.write(rocco.to_html) }
+end

data/lib/rocco.rb

@@ -0,0 +1,153 @@
+# **Rocco** is a Ruby port of [Docco][do], the quick-and-dirty,
+# hundred-line-long, literate-programming-style documentation generator.
+#
+# Rocco reads Ruby source files and produces annotated source documentation
+# in HTML format. Comments are formatted with [Markdown][md] and presented
+# alongside syntax highlighted code so as to give an annotation effect.
+# This page is the result of running Rocco against its own source file.
+#
+# Most of this was written while waiting for [node.js][no] to build (so I
+# could use Docco!). Docco's gorgeous HTML and CSS are taken verbatim.
+# The main difference is that Rocco is written in Ruby instead of
+# [CoffeeScript][co] and may be a bit easier to obtain and install in
+# existing Ruby environments or where node doesn't run yet.
+#
+# Rocco can be installed with rubygems:
+#
+#     gem install rocco
+#
+# Once installed, the `rocco` command can be used to generate documentation
+# for a set of Ruby source files:
+#
+#     rocco lib/*.rb
+#
+# The HTML files are written to the current working directory.
+#
+# [no]: http://nodejs.org/
+# [do]: http://jashkenas.github.com/docco/
+# [co]: http://coffeescript.org/
+# [md]: http://daringfireball.net/projects/markdown/
+
+#### Prerequisites
+
+# The [rdiscount](http://github.com/rtomayko/rdiscount) library is
+# required for Markdown processing.
+require 'rdiscount'
+
+# We use [{{ mustache }}](http://defunkt.github.com/mustache/) for
+# templating.
+require 'mustache'
+
+# Code is run through [Pygments](http://pygments.org/) for syntax
+# highlighting. Fail fast if we can't find the `pygmentize` program.
+if ! ENV['PATH'].split(':').any? { |dir| File.exist?("#{dir}/pygmentize") }
+  fail "Pygments is required for syntax highlighting"
+end
+
+#### Public Interface
+
+# `Rocco.new` takes a source `filename` and an optional `block`.
+# When `block` is given, it must read the contents of the file using
+# whatever means necessary and return it as a string. With no `block`, the
+# file is read to retrieve data.
+class Rocco
+  VERSION = '0.1'
+
+  def initialize(filename, &block)
+    @file = filename
+    @data =
+      if block_given?
+        yield
+      else
+        File.read(filename)
+      end
+    # Parsing and highlighting
+    @sections = highlight(parse(@data))
+  end
+
+  # The filename as given to `Rocco.new`.
+  attr_reader :file
+
+  # A list of two-tuples representing each *section* of the source file. Each
+  # item in the list has the form: `[docs_html, code_html]`, where both
+  # elements are strings containing the documentation and source code HTML,
+  # respectively.
+  attr_reader :sections
+
+  # Generate HTML output for the entire document.
+  require 'rocco/layout'
+  def to_html
+    Rocco::Layout.new(self).render
+  end
+
+  #### Internal Parsing and Highlighting
+
+  # Parse the raw file data into a list of two-tuples.
+  def parse(data)
+    sections = []
+    docs, code = [], []
+    data.split("\n").each do |line|
+      case line
+      when /^\s*#/
+        if code.any?
+          sections << [docs, code]
+          docs, code = [], []
+        end
+        docs << line
+      when /^\s*$/
+        code << line
+      else
+        code << line
+      end
+    end
+    sections << [docs, code] if docs.any? || code.any?
+    sections
+  end
+
+  # Take the raw section data and apply markdown formatting and syntax
+  # highlighting.
+  def highlight(sections)
+    # Start by splitting the docs and codes blocks into two separate lists.
+    docs_blocks, code_blocks = [], []
+    sections.each do |docs,code|
+      docs_blocks << docs.map { |line| line.sub(/^\s*#\s?/, '') }.join("\n")
+      code_blocks << code.join("\n")
+    end
+
+    # Combine all docs blocks into a single big markdown document and run
+    # through RDiscount. Then split it back out into separate sections.
+    markdown = docs_blocks.join("\n##### DIVIDER\n")
+    docs_html = Markdown.new(markdown, :smart).
+      to_html.
+      split("\n<h5>DIVIDER</h5>\n")
+
+    # Combine all code blocks into a single big stream and run through
+    # pygments. We `popen` a pygmentize process and then fork off a
+    # writer process.
+    code_html = nil
+    open("|pygmentize -l ruby -f html", 'r+') do |fd|
+      fork {
+        fd.close_read
+        fd.write code_blocks.join("\n# DIVIDER\n")
+        fd.close_write
+        exit!
+      }
+
+      fd.close_write
+      code_html = fd.read
+      fd.close_read
+    end
+
+    # Do some post-processing on the pygments output to remove
+    # partial `<pre>` blocks. We'll add these back when we build to main
+    # document.
+    code_html = code_html.
+      split(/\n?<span class="c1"># DIVIDER<\/span>\n?/m).
+      map { |code| code.sub(/\n?<div class="highlight"><pre>/m, '') }.
+      map { |code| code.sub(/\n?<\/pre><\/div>\n/m, '') }
+
+    # Combine the docs and code lists into the same sections style list we
+    # started with.
+    docs_html.zip(code_html)
+  end
+end

data/lib/rocco/layout.mustache

@@ -0,0 +1,28 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <meta http-equiv="content-type" content="text/html;charset=utf-8">
+  <title>{{ title }}</title>
+  <link rel="stylesheet" href="http://jashkenas.github.com/docco/resources/docco.css">
+</head>
+<body>
+<div id='container'>
+  <table cellspacing=0 cellpadding=0>
+  <thead>
+    <tr>
+      <th class=docs><h1>{{ title }}</h1></th>
+      <th class=code></th>
+    </tr>
+  </thead>
+  <tbody>
+    {{#sections}}
+    <tr id='section-{{ num }}'>
+      <td class=docs>{{{ docs }}}</td>
+      <td class=code>
+        <div class='highlight'><pre>{{{ code }}}</pre></div>
+      </td>
+    </tr>
+    {{/sections}}
+  </table>
+</div>
+</body>

data/lib/rocco/layout.rb

@@ -0,0 +1,24 @@
+require 'mustache'
+
+class Rocco::Layout < Mustache
+  self.template_path = File.dirname(__FILE__)
+
+  def initialize(doc)
+    @doc = doc
+  end
+
+  def title
+    File.basename(@doc.file)
+  end
+
+  def sections
+    num = 0
+    @doc.sections.map do |docs,code|
+      {
+        :docs  => docs,
+        :code  => code,
+        :num   => (num += 1)
+      }
+    end
+  end
+end

data/rocco.gemspec

@@ -0,0 +1,38 @@
+Gem::Specification.new do |s|
+  s.specification_version = 2 if s.respond_to? :specification_version=
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+
+  s.name = 'rocco'
+  s.version = '0.1'
+  s.date = '2010-03-08'
+
+  s.description = "Docco in Ruby"
+  s.summary     = s.description
+
+  s.authors = ["Ryan Tomayko"]
+  s.email = "r@tomayko.com"
+
+  # = MANIFEST =
+  s.files = %w[
+    COPYING
+    README.md
+    Rakefile
+    bin/rocco
+    lib/rocco.rb
+    lib/rocco/layout.mustache
+    lib/rocco/layout.rb
+    rocco.gemspec
+  ]
+  # = MANIFEST =
+
+  s.executables = ["rocco"]
+
+  s.test_files = s.files.select {|path| path =~ /^test\/.*_test.rb/}
+  s.add_dependency 'rdiscount'
+  s.add_dependency 'mustache'
+
+  s.has_rdoc = false
+  s.homepage = "http://rtomayko.github.com/rocco/"
+  s.require_paths = %w[lib]
+  s.rubygems_version = '1.1.1'
+end

metadata

@@ -0,0 +1,91 @@
+--- !ruby/object:Gem::Specification 
+name: rocco
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 0
+  - 1
+  version: "0.1"
+platform: ruby
+authors: 
+- Ryan Tomayko
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-03-08 00:00:00 -08:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rdiscount
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        version: "0"
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: mustache
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        version: "0"
+  type: :runtime
+  version_requirements: *id002
+description: Docco in Ruby
+email: r@tomayko.com
+executables: 
+- rocco
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- COPYING
+- README.md
+- Rakefile
+- bin/rocco
+- lib/rocco.rb
+- lib/rocco/layout.mustache
+- lib/rocco/layout.rb
+- rocco.gemspec
+has_rdoc: true
+homepage: http://rtomayko.github.com/rocco/
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.6
+signing_key: 
+specification_version: 2
+summary: Docco in Ruby
+test_files: []
+