rocco-obb 0.5

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

@@ -0,0 +1,23 @@
+
+
+                  ___       ___       ___       ___       ___
+                 /\  \     /\  \     /\  \     /\  \     /\  \
+                /::\  \   /::\  \   /::\  \   /::\  \   /::\  \
+               /::\:\__\ /:/\:\__\ /:/\:\__\ /:/\:\__\ /:/\:\__\
+               \;:::/  / \:\/:/  / \:\ \/__/ \:\ \/__/ \:\/:/  /
+                |:\/__/   \::/  /   \:\__\    \:\__\    \::/  /
+                 \|__|     \/__/     \/__/     \/__/     \/__/
+
+
+
+    Rocco is  a quick-and-dirty,  literate-programming-style documentation
+    generator for Ruby. See the Rocco generated docs for more information:
+
+                    <http://rtomayko.github.com/rocco/>
+
+
+    Rocco is a port of,  and borrows heavily from, Docco  -- the original
+    quick-and-dirty,   hundred-line-long,   literate-programming-style
+    documentation generator in CoffeeScript:
+
+                    <http://jashkenas.github.com/docco/>

data/Rakefile

@@ -0,0 +1,115 @@
+$LOAD_PATH.unshift 'lib'
+
+require 'rake/testtask'
+require 'rake/clean'
+
+task :default => [:sup, :docs, :test]
+
+desc 'Holla'
+task :sup do
+  verbose do
+    lines = File.read('README').split("\n")[0,12]
+    lines.map! { |line| line[15..-1] }
+    puts lines.join("\n")
+  end
+end
+
+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
+
+# Bring in Rocco tasks
+require 'rocco/tasks'
+Rocco::make 'docs/'
+
+desc 'Build rocco docs'
+task :docs => :rocco
+directory 'docs/'
+
+desc 'Build docs and open in browser for the reading'
+task :read => :docs do
+  sh 'open docs/rocco.html'
+end
+
+# Make index.html a copy of rocco.html
+file 'docs/index.html' => 'docs/rocco.html' do |f|
+  cp 'docs/rocco.html', 'docs/index.html', :preserve => true
+end
+task :docs => 'docs/index.html'
+CLEAN.include 'docs/index.html'
+
+# Alias for docs task
+task :doc => :docs
+
+# GITHUB PAGES ===============================================================
+
+desc 'Update gh-pages branch'
+task :pages => ['docs/.git', :docs] do
+  rev = `git rev-parse --short HEAD`.strip
+  Dir.chdir 'docs' do
+    sh "git add *.html"
+    sh "git commit -m 'rebuild pages from #{rev}'" do |ok,res|
+      if ok
+        verbose { puts "gh-pages updated" }
+        sh "git push -q o HEAD:gh-pages"
+      end
+    end
+  end
+end
+
+# Update the pages/ directory clone
+file 'docs/.git' => ['docs/', '.git/refs/heads/gh-pages'] do |f|
+  sh "cd docs && git init -q && git remote add o ../.git" if !File.exist?(f.name)
+  sh "cd docs && git fetch -q o && git reset -q --hard o/gh-pages && touch ."
+end
+CLOBBER.include 'docs/.git'
+
+# 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|
+  version = File.read('lib/rocco.rb')[/VERSION = '(.*)'/] && $1
+  date = Time.now.strftime("%Y-%m-%d")
+  spec = File.
+    read(f.name).
+    sub(/s\.version\s*=\s*'.*'/, "s.version = '#{version}'")
+  parts = spec.split("  # = MANIFEST =\n")
+  files = `git ls-files`.
+    split("\n").sort.reject{ |file| file =~ /^\./ }.
+    map{ |file| "    #{file}" }.join("\n")
+  parts[1] = "  s.files = %w[\n#{files}\n  ]\n"
+  spec = parts.join("  # = MANIFEST =\n")
+  spec.sub!(/s.date = '.*'/, "s.date = '#{date}'")
+  File.open(f.name, 'w') { |io| io.write(spec) }
+  puts "#{f.name} #{version} (#{date})"
+end

data/bin/rocco

@@ -0,0 +1,97 @@
+#!/usr/bin/env ruby
+#/ Usage: rocco [-l <lang>] [-c <chars>] [-o <dir>] <file>...
+#/ Generate literate-programming-style documentation for Ruby source <file>s.
+#/
+#/ Options:
+#/   -l, --language=<lang>  The Pygments lexer to use to highlight code
+#/   -c, --comment-chars=<chars>
+#/                          The string to recognize as a comment marker
+#/   -o, --output=<dir>     Directory where generated HTML files are written
+#/   -t, --template=<path>  The file to use as template when rendering HTML
+#/       --help             Show this help message
+
+require 'optparse'
+require 'fileutils'
+
+# Write usage message to stdout and exit.
+def usage(stream=$stderr, status=1)
+  stream.puts File.readlines(__FILE__).
+    grep(/^#\//).
+    map { |line| line.sub(/^#. ?/, '') }.
+    join
+  exit status
+end
+
+# Like `Kernel#abort` but writes a note encouraging the user to consult
+# `rocco --help` for more information.
+def abort_with_note(message=nil)
+  $stderr.puts message if message
+  abort "See `rocco --help' for usage information."
+end
+
+# Parse command line options, aborting if anything goes wrong.
+output_dir = '.'
+sources = []
+options = {}
+ARGV.options { |o|
+  o.program_name = File.basename($0)
+  o.on("-o", "--output=DIR") { |dir| output_dir = dir }
+  o.on("-l", "--language=LANG") { |lang| options[:language] = lang }
+  o.on("-c", "--comment-chars=CHARS") { |chars| options[:comment_chars] = Regexp.escape(chars) }
+  o.on("-t", "--template=TEMPLATE") { |template| options[:template_file] = template }
+  o.on_tail("-h", "--help") { usage($stdout, 0) }
+  o.parse!
+} or abort_with_note
+
+# Use http://pygments.appspot.com in case `pygmentize(1)` isn't available.
+if ! ENV['PATH'].split(':').any? { |dir| File.exist?("#{dir}/pygmentize") }
+  unless options[:webservice]
+    $stderr.puts "pygmentize not in PATH; using pygments.appspot.com instead"
+    options[:webservice] = true
+  end
+end
+
+# Eat sources from ARGV.
+sources << ARGV.shift while ARGV.any?
+
+# Make sure we have some files to work with.
+if sources.empty?
+  abort_with_note "#{File.basename($0)}: no input <file>s given"
+end
+
+# What a fucking mess. Most of this is duplicated in rocco.rb too.
+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
+    else
+      require 'bluecloth'
+      Markdown = BlueCloth
+      $LOADED_FEATURES << 'rdiscount.rb'
+      retry
+    end
+  when /rocco/
+    if !$:.include?(libdir)
+      warn "warn: #$!. trying again with #{libdir} on load path"
+      $:.unshift(libdir)
+      retry
+    end
+  end
+  raise
+end
+
+# Run each file through Rocco and write output.
+sources.each do |filename|
+  rocco = Rocco.new(filename, sources, options)
+  dest = File.join(output_dir, (filename.split('.')[0..-2].empty? ? filename : filename.split('.')[0..-2].join('.')) + '.html')
+  puts "rocco: #{filename} -> #{dest}"
+  FileUtils.mkdir_p File.dirname(dest)
+  File.open(dest, 'wb') { |fd| fd.write(rocco.to_html) }
+end

data/lib/rocco/layout.mustache

@@ -0,0 +1,46 @@
+<!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'>
+  <div id="background"></div>
+  {{#sources?}}
+  <div id="jump_to">
+    Jump To &hellip;
+    <div id="jump_wrapper">
+      <div id="jump_page">
+        {{#sources}}
+          <a class="source" href="{{ url }}">{{ basename }}</a>
+        {{/sources}}
+      </div>
+    </div>
+  </div>
+  {{/sources?}}
+  <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>
+        <div class="pilwrap">
+          <a class="pilcrow" href="#section-{{ num }}">&#182;</a>
+        </div>
+        {{{ 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,47 @@
+require 'mustache'
+
+class Rocco::Layout < Mustache
+  self.template_path = File.dirname(__FILE__)
+
+  def initialize(doc, file=nil)
+    @doc = doc
+    if not file.nil?
+      Rocco::Layout.template_file = file
+    end
+  end
+
+  def title
+    File.basename(@doc.file)
+  end
+
+  def sections
+    num = 0
+    @doc.sections.map do |docs,code|
+      {
+        :docs       =>  docs,
+        :docs?      =>  !docs.empty?,
+        :header?    =>  /^<h.>.+<\/h.>$/.match( docs ),
+
+        :code       =>  code,
+        :code?      =>  !code.empty?,
+
+        :empty?     =>  ( code.empty? && docs.empty? ),
+        :num        =>  (num += 1)
+      }
+    end
+  end
+
+  def sources?
+    @doc.sources.length > 1
+  end
+
+  def sources
+    @doc.sources.sort.map do |source|
+      {
+        :path => source,
+        :basename => File.basename(source),
+        :url => File.basename(source).split('.')[0..-2].join('.') + '.html'
+      }
+    end
+  end
+end

data/lib/rocco/tasks.rb

@@ -0,0 +1,120 @@
+#### Rocco Rake Tasks
+#
+# To use the Rocco Rake tasks, require `rocco/tasks` in your `Rakefile`
+# and define a Rake task with `rocco_task`. In its simplest form, `rocco_task`
+# takes the path to a destination directory where HTML docs should be built:
+#
+#     require 'rocco/tasks'
+#
+#     desc "Build Rocco Docs"
+#     Rocco::make 'docs/'
+#
+# This creates a `:rocco` rake task, which can then be run with:
+#
+#     rake rocco
+#
+# It's a good idea to guard against Rocco not being available, since your
+# Rakefile will fail to load otherwise. Consider doing something like this,
+# so that your Rakefile will still work
+#
+#     begin
+#       require 'rocco/tasks'
+#       Rocco::make 'docs/'
+#     rescue LoadError
+#       warn "#$! -- rocco tasks not loaded."
+#       task :rocco
+#     end
+#
+# It's also possible to pass a glob pattern:
+#
+#     Rocco::make 'html/', 'lib/thing/**/*.rb'
+#
+# Or a list of glob patterns:
+#
+#     Rocco::make 'html/', ['lib/thing.rb', 'lib/thing/*.rb']
+#
+# Finally, it is also possible to specify which Pygments language you would
+# like to use to highlight the code, as well as the comment characters for the
+# language in the `options` hash:
+#
+#    Rocco::make 'html/', 'lib/thing/**/*.rb', {
+#      :language => 'io',
+#      :comment_chars => '#'
+#    }
+#
+
+# Might be nice to defer this until we actually need to build docs but this
+# will have to do for now.
+require 'rocco'
+
+# Reopen the Rocco class and add a `make` class method. This is a simple bit
+# of sugar over `Rocco::Task.new`. If you want your Rake task to be named
+# something other than `:rocco`, you can use `Rocco::Task` directly.
+class Rocco
+  def self.make(dest='docs/', source_files='lib/**/*.rb', options={})
+    Task.new(:rocco, dest, source_files, options)
+  end
+
+  # `Rocco::Task.new` takes a task name, the destination directory docs
+  # should be built under, and a source file pattern or file list.
+  class Task
+    def initialize(task_name, dest='docs/', sources='lib/**/*.rb', options={})
+      @name = task_name
+      @dest = dest[-1] == ?/ ? dest : "#{dest}/"
+      @sources = FileList[sources]
+      @options = options
+
+      # Make sure there's a `directory` task defined for our destination.
+      define_directory_task @dest
+
+      # Run over the source file list, constructing destination filenames
+      # and defining file tasks.
+      @sources.each do |source_file|
+        dest_file = File.basename(source_file).split('.')[0..-2].join('.') + '.html'
+        define_file_task source_file, "#{@dest}#{dest_file}"
+
+        # If `rake/clean` was required, add the generated files to the list.
+        # That way all Rocco generated are removed when running `rake clean`.
+        CLEAN.include "#{@dest}#{dest_file}" if defined? CLEAN
+      end
+    end
+
+    # Define the destination directory task and make the `:rocco` task depend
+    # on it. This causes the destination directory to be created if it doesn't
+    # already exist.
+    def define_directory_task(path)
+      directory path
+      task @name => path
+    end
+
+    # Setup a `file` task for a single Rocco output file (`dest_file`). It
+    # depends on the source file, the destination directory, and all of Rocco's
+    # internal source code, so that the destination file is rebuilt when any of
+    # those changes.
+    #
+    # You can run these tasks directly with Rake:
+    #
+    #     rake docs/foo.html docs/bar.html
+    #
+    # ... would generate the `foo.html` and `bar.html` files but only if they
+    # don't already exist or one of their dependencies was changed.
+    def define_file_task(source_file, dest_file)
+      prerequisites = [@dest, source_file] + rocco_source_files
+      file dest_file => prerequisites do |f|
+        verbose { puts "rocco: #{source_file} -> #{dest_file}" }
+        rocco = Rocco.new(source_file, @sources.to_a, @options)
+        File.open(dest_file, 'wb') { |fd| fd.write(rocco.to_html) }
+      end
+      task @name => dest_file
+    end
+
+    # Return a `FileList` that includes all of Roccos source files. This causes
+    # output files to be regenerated properly when someone upgrades the Rocco
+    # library.
+    def rocco_source_files
+      libdir = File.expand_path('../..', __FILE__)
+      FileList["#{libdir}/rocco.rb", "#{libdir}/rocco/**"]
+    end
+
+  end
+end

data/lib/rocco.rb

@@ -0,0 +1,324 @@
+# **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][so].
+#
+# 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.
+#
+# Install Rocco 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/
+# [so]: http://github.com/rtomayko/rocco/blob/master/lib/rocco.rb#commit
+
+#### Prerequisites
+
+# We'll need a Markdown library. [RDiscount][rd], if we're lucky. Otherwise,
+# issue a warning and fall back on using BlueCloth.
+#
+# [rd]: http://github.com/rtomayko/rdiscount
+begin
+  require 'rdiscount'
+rescue LoadError => boom
+  warn "WARNING: #{boom}. Trying bluecloth."
+  require 'bluecloth'
+  Markdown = BlueCloth
+end
+
+# We use [{{ mustache }}](http://defunkt.github.com/mustache/) for
+# HTML templating.
+require 'mustache'
+
+# We use `Net::HTTP` to highlight code via <http://pygments.appspot.com>
+require 'net/http'
+
+# Code is run through [Pygments](http://pygments.org/) for syntax
+# highlighting. If it's not installed, locally, use a webservice.
+include FileTest
+if !ENV['PATH'].split(':').any? { |dir| executable?("#{dir}/pygmentize") }
+  warn "WARNING: Pygments not found. Using webservice."
+end
+
+#### Public Interface
+
+# `Rocco.new` takes a source `filename`, an optional list of source filenames
+# for other documentation sources, an `options` hash, and an optional `block`.
+# The `options` hash respects three members:
+#
+# *    `:language`: specifies which Pygments lexer to use if one can't be
+#      auto-detected from the filename.  _Defaults to `ruby`_.
+# 
+# *    `:comment_chars`, which specifies the comment characters of the
+#      target language. _Defaults to `#`_.
+#
+# *    `:template_file`, which specifies a external template file to use
+#      when rendering the final, highlighted file via Mustache.  _Defaults
+#      to `nil` (that is, Mustache will use `./lib/rocco/layout.mustache`)_.
+#
+class Rocco
+  VERSION = '0.5'
+
+  def initialize(filename, sources=[], options={}, &block)
+    @file       = filename
+    @sources    = sources
+
+    # 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.
+    @data =
+      if block_given?
+        yield
+      else
+        File.read(filename)
+      end
+    defaults = {
+      :language      => 'ruby',
+      :comment_chars => '#',
+      :template_file => nil
+    }
+    @options = defaults.merge(options)
+    @template_file = @options[:template_file]
+
+    # If we detect a language
+    if detect_language() != "text"
+        # then assign the detected language to `:language`
+        @options[:language] = detect_language()
+        # and look for some comment characters
+        @options[:comment_chars]    = generate_comment_chars()
+    # If we didn't detect a language, but the user provided one, use it
+    # to look around for comment characters to override the default.
+    elsif @options[:language] != defaults[:language]
+        @options[:comment_chars]    = generate_comment_chars()
+    end
+    @comment_pattern            = Regexp.new("^\\s*#{@options[:comment_chars]}\s?")
+
+    @sections = highlight(split(parse(@data)))
+  end
+
+  # Returns `true` if `pygmentize` is available locally, `false` otherwise.
+  def pygmentize?
+    # Memoize the result, we'll call this a few times
+    @_pygmentize ||= ENV['PATH'].split(':').any? { |dir| executable?("#{dir}/pygmentize") }
+  end
+
+  # If `pygmentize` is available, we can use it to autodetect a file's
+  # language based on its filename.  Filenames without extensions, or with
+  # extensions that `pygmentize` doesn't understand will return `text`.
+  # We'll also return `text` if `pygmentize` isn't available.
+  #
+  # We'll memoize the result, as we'll call this a few times.
+  def detect_language
+    @_language ||= begin
+        if pygmentize?
+            lang = %x[pygmentize -N #{@file}].strip!
+        else
+            "text"
+        end
+    end
+  end
+
+  # Given a file's language, we should be able to autopopulate the 
+  # `comment_chars` variables for single-line comments.  If we don't
+  # have comment characters on record for a given language, we'll
+  # use the user-provided `:comment_char` option (which defaults to
+  # `#`).
+  #
+  # Comment characters are listed as:
+  # 
+  #     { :single => "//", :multi_start => "/**", :multi_middle => "*", :multi_end => "*/" }
+  #
+  # `:single` denotes the leading character of a single-line comment.
+  # `:multi_start` denotes the string that should appear alone on a
+  # line of code to begin a block of documentation.  `:multi_middle`
+  # denotes the leading character of block comment content, and
+  # `:multi_end` is the string that ought appear alone on a line to
+  # close a block of documentation.  That is:
+  #
+  #     /**                 [:multi][:start]
+  #      *                  [:multi][:middle] 
+  #      *                  [:multi][:middle] 
+  #      *                  [:multi][:middle] 
+  #      */                 [:multi][:end]
+  #
+  # If a language only has one type of comment, the missing type
+  # should be assigned `nil`.
+  #
+  # At the moment, we're only returning `:single`.  Consider this
+  # groundwork for block comment parsing.
+  def generate_comment_chars
+    @_commentchar ||= begin
+        language        = @options[:language]
+        comment_styles  = {
+            "bash"          =>  { :single => "#",   :multi => nil },
+            "c"             =>  { :single => "//",  :multi => { :start => "/**", :middle => "*", :end => "*/" } },
+            "coffee-script" =>  { :single => "#",   :multi => { :start => "###", :middle => nil, :end => "###" } },
+            "cpp"           =>  { :single => "//",  :multi => { :start => "/**", :middle => "*", :end => "*/" } },
+            "java"          =>  { :single => "//",  :multi => { :start => "/**", :middle => "*", :end => "*/" } },
+            "js"            =>  { :single => "//",  :multi => { :start => "/**", :middle => "*", :end => "*/" } },
+            "php"           =>  { :single => "//",  :multi => { :start => "/**", :middle => "*", :end => "*/" } },
+            "lua"           =>  { :single => "--",  :multi => nil },
+            "python"        =>  { :single => "#",   :multi => { :start => '"""', :middle => nil, :end => '"""' } },
+            "ruby"          =>  { :single => "#",   :multi => nil },
+            "scheme"        =>  { :single => ";;",  :multi => nil },
+        }
+        
+        if comment_styles[language]
+            comment_styles[language][:single]
+        else
+            @options[:comment_chars]
+        end
+    end
+  end
+
+  # The filename as given to `Rocco.new`.
+  attr_reader :file
+
+  # The merged options array
+  attr_reader :options
+
+  # 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
+
+  # A list of all source filenames included in the documentation set. Useful
+  # for building an index of other files.
+  attr_reader :sources
+
+  # An absolute path to a file that ought be used as a template for the
+  # HTML-rendered documentation.
+  attr_reader :template_file
+
+  # Generate HTML output for the entire document.
+  require 'rocco/layout'
+  def to_html
+    Rocco::Layout.new(self, @template_file).render
+  end
+
+  #### Internal Parsing and Highlighting
+
+  # Parse the raw file data into a list of two-tuples. Each tuple has the
+  # form `[docs, code]` where both elements are arrays containing the
+  # raw lines parsed from the input file. The first line is ignored if it
+  # is a shebang line.
+  def parse(data)
+    sections = []
+    docs, code = [], []
+    lines = data.split("\n")
+    lines.shift if lines[0] =~ /^\#\!/
+    lines.each do |line|
+      case line
+      when @comment_pattern
+        if code.any?
+          sections << [docs, code]
+          docs, code = [], []
+        end
+        docs << line
+      else
+        code << line
+      end
+    end
+    sections << [docs, code] if docs.any? || code.any?
+    sections
+  end
+
+  # Take the list of paired *sections* two-tuples and split into two
+  # separate lists: one holding the comments with leaders removed and
+  # one with the code blocks.
+  def split(sections)
+    docs_blocks, code_blocks = [], []
+    sections.each do |docs,code|
+      docs_blocks << docs.map { |line| line.sub(@comment_pattern, '') }.join("\n")
+      code_blocks << code.map do |line|
+        tabs = line.match(/^(\t+)/)
+        tabs ? line.sub(/^\t+/, '  ' * tabs.captures[0].length) : line
+      end.join("\n")
+    end
+    [docs_blocks, code_blocks]
+  end
+
+  # Take the result of `split` and apply Markdown formatting to comments and
+  # syntax highlighting to source code.
+  def highlight(blocks)
+    docs_blocks, code_blocks = blocks
+
+    # Combine all docs blocks into a single big markdown document with section
+    # dividers and run through the Markdown processor. Then split it back out
+    # into separate sections.
+    markdown = docs_blocks.join("\n\n##### DIVIDER\n\n")
+    docs_html = Markdown.new(markdown, :smart).
+      to_html.
+      split(/\n*<h5>DIVIDER<\/h5>\n*/m)
+
+    # Combine all code blocks into a single big stream and run through either
+    # `pygmentize(1)` or <http://pygments.appspot.com>
+    code_stream = code_blocks.join("\n\n#{@options[:comment_chars]} DIVIDER\n\n")
+
+    if pygmentize? 
+      code_html = highlight_pygmentize(code_stream)
+    else 
+      code_html = highlight_webservice(code_stream)
+    end
+
+    # Do some post-processing on the pygments output to split things back
+    # into sections and remove partial `<pre>` blocks.
+    code_html = code_html.
+      split(/\n*<span class="c.?">#{@options[:comment_chars]} DIVIDER<\/span>\n*/m).
+      map { |code| code.sub(/\n?<div class="highlight"><pre>/m, '') }.
+      map { |code| code.sub(/\n?<\/pre><\/div>\n/m, '') }
+
+    # Lastly, combine the docs and code lists back into a list of two-tuples.
+    docs_html.zip(code_html)
+  end
+
+  # We `popen` a read/write pygmentize process in the parent and
+  # then fork off a child process to write the input.
+  def highlight_pygmentize(code)
+    code_html = nil
+    open("|pygmentize -l #{@options[:language]} -O encoding=utf-8 -f html", 'r+') do |fd|
+      pid =
+        fork {
+          fd.close_read
+          fd.write code
+          fd.close_write
+          exit!
+        }
+      fd.close_write
+      code_html = fd.read
+      fd.close_read
+      Process.wait(pid)
+    end
+
+    code_html
+  end
+  
+  # Pygments is not one of those things that's trivial for a ruby user to install,
+  # so we'll fall back on a webservice to highlight the code if it isn't available.
+  def highlight_webservice(code)
+    Net::HTTP.post_form(
+      URI.parse('http://pygments.appspot.com/'),
+      {'lang' => @options[:language], 'code' => code}
+    ).body
+  end
+end
+
+# And that's it.

data/rocco.gemspec

@@ -0,0 +1,39 @@
+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-obb'
+  s.version = '0.5'
+  s.date = '2010-09-10'
+
+  s.description = "Docco in Ruby"
+  s.summary     = s.description
+
+  s.authors = ["Ryan Tomayko"]
+  s.email = "r@tomayko.com"
+
+  # = MANIFEST =
+  s.files = %w[
+    COPYING
+    README
+    Rakefile
+    bin/rocco
+    lib/rocco.rb
+    lib/rocco/layout.mustache
+    lib/rocco/layout.rb
+    lib/rocco/tasks.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://github.com/oneblackbear/rocco/"
+  s.require_paths = %w[lib]
+  s.rubygems_version = '1.1.1'
+end

metadata

@@ -0,0 +1,101 @@
+--- !ruby/object:Gem::Specification 
+name: rocco-obb
+version: !ruby/object:Gem::Version 
+  hash: 1
+  prerelease: false
+  segments: 
+  - 0
+  - 5
+  version: "0.5"
+platform: ruby
+authors: 
+- Ryan Tomayko
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-09-10 00:00:00 +01:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rdiscount
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: mustache
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        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
+- Rakefile
+- bin/rocco
+- lib/rocco.rb
+- lib/rocco/layout.mustache
+- lib/rocco/layout.rb
+- lib/rocco/tasks.rb
+- rocco.gemspec
+has_rdoc: true
+homepage: http://github.com/oneblackbear/rocco/
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 2
+summary: Docco in Ruby
+test_files: []
+