rocco 0.1 → 0.2

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

@@ -1,5 +1,18 @@
+$LOAD_PATH.unshift 'lib'
+
 require 'rake/testtask'
-task :default => :test
+require 'rake/clean'
+
+task :default => [:sup, :docs]
+
+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|
@@ -7,6 +20,52 @@ Rake::TestTask.new(:test) do |t|
   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)
@@ -39,21 +98,18 @@ 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
+  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")
-  # 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")}'")
+  spec.sub!(/s.date = '.*'/, "s.date = '#{date}'")
   File.open(f.name, 'w') { |io| io.write(spec) }
-  puts "updated #{f.name}"
+  puts "#{f.name} #{version} (#{date})"
 end

data/bin/rocco

@@ -11,6 +11,11 @@ rescue LoadError
       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)

data/lib/rocco.rb

@@ -4,7 +4,7 @@
 # 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.
+# 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.
@@ -12,7 +12,7 @@
 # [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:
+# Install Rocco with Rubygems:
 #
 #     gem install rocco
 #
@@ -27,19 +27,29 @@
 # [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
 
-# The [rdiscount](http://github.com/rtomayko/rdiscount) library is
-# required for Markdown processing.
-require 'rdiscount'
+# 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 "warn: #{boom}. trying bluecloth"
+  require 'bluecloth'
+  Markdown = BlueCloth
+end
 
 # We use [{{ mustache }}](http://defunkt.github.com/mustache/) for
-# templating.
+# HTML templating.
 require 'mustache'
 
 # Code is run through [Pygments](http://pygments.org/) for syntax
-# highlighting. Fail fast if we can't find the `pygmentize` program.
+# highlighting. Fail fast right here if we can't find the `pygmentize`
+# program on PATH.
 if ! ENV['PATH'].split(':').any? { |dir| File.exist?("#{dir}/pygmentize") }
   fail "Pygments is required for syntax highlighting"
 end
@@ -51,7 +61,7 @@ end
 # whatever means necessary and return it as a string. With no `block`, the
 # file is read to retrieve data.
 class Rocco
-  VERSION = '0.1'
+  VERSION = '0.2'
 
   def initialize(filename, &block)
     @file = filename
@@ -61,8 +71,7 @@ class Rocco
       else
         File.read(filename)
       end
-    # Parsing and highlighting
-    @sections = highlight(parse(@data))
+    @sections = highlight(split(parse(@data)))
   end
 
   # The filename as given to `Rocco.new`.
@@ -82,7 +91,9 @@ class Rocco
 
   #### Internal Parsing and Highlighting
 
-  # Parse the raw file data into a list of two-tuples.
+  # 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.
   def parse(data)
     sections = []
     docs, code = [], []
@@ -94,8 +105,6 @@ class Rocco
           docs, code = [], []
         end
         docs << line
-      when /^\s*$/
-        code << line
       else
         code << line
       end
@@ -104,50 +113,59 @@ class Rocco
     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.
+  # 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(/^\s*#\s?/, '') }.join("\n")
       code_blocks << code.join("\n")
     end
+    [docs_blocks, code_blocks]
+  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")
+  # 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")
+      split(/\n*<h5>DIVIDER<\/h5>\n*/m)
 
     # 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.
+    # Pygments. We `popen` a read/write pygmentize process in the parent and
+    # then fork off a child process to write the input.
     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!
-      }
-
+      pid =
+        fork {
+          fd.close_read
+          fd.write code_blocks.join("\n\n# DIVIDER\n\n")
+          fd.close_write
+          exit!
+        }
       fd.close_write
       code_html = fd.read
       fd.close_read
+      Process.wait(pid)
     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.
+    # 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="c1"># DIVIDER<\/span>\n?/m).
+      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.
+    # Lastly, combine the docs and code lists back into a list of two-tuples.
     docs_html.zip(code_html)
   end
 end
+
+# And that's it.

data/lib/rocco/layout.mustache

@@ -7,6 +7,7 @@
 </head>
 <body>
 <div id='container'>
+  <div id="background"></div>
   <table cellspacing=0 cellpadding=0>
   <thead>
     <tr>
@@ -17,7 +18,12 @@
   <tbody>
     {{#sections}}
     <tr id='section-{{ num }}'>
-      <td class=docs>{{{ docs }}}</td>
+      <td class=docs>
+        <div class="octowrap">
+          <a class="octothorpe" href="#section-{{ num }}">#</a>
+        </div>
+        {{{ docs }}}
+      </td>
       <td class=code>
         <div class='highlight'><pre>{{{ code }}}</pre></div>
       </td>

data/lib/rocco/tasks.rb

@@ -0,0 +1,110 @@
+#### 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']
+#
+
+# 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')
+    Task.new(:rocco, dest, source_files)
+  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')
+      @name = task_name
+      @dest = dest[-1] == ?/ ? dest : "#{dest}/"
+      @sources = FileList[sources]
+
+      # 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, '.rb') + '.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)
+        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/rocco.gemspec

@@ -3,8 +3,8 @@ Gem::Specification.new do |s|
   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.version = '0.2'
+  s.date = '2010-03-11'
 
   s.description = "Docco in Ruby"
   s.summary     = s.description
@@ -15,12 +15,13 @@ Gem::Specification.new do |s|
   # = MANIFEST =
   s.files = %w[
     COPYING
-    README.md
+    README
     Rakefile
     bin/rocco
     lib/rocco.rb
     lib/rocco/layout.mustache
     lib/rocco/layout.rb
+    lib/rocco/tasks.rb
     rocco.gemspec
   ]
   # = MANIFEST =

metadata

@@ -4,8 +4,8 @@ version: !ruby/object:Gem::Version
   prerelease: false
   segments: 
   - 0
-  - 1
-  version: "0.1"
+  - 2
+  version: "0.2"
 platform: ruby
 authors: 
 - Ryan Tomayko
@@ -13,7 +13,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-03-08 00:00:00 -08:00
+date: 2010-03-11 00:00:00 -08:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -50,12 +50,13 @@ extra_rdoc_files: []
 
 files: 
 - COPYING
-- README.md
+- 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://rtomayko.github.com/rocco/

data/README.md

@@ -1,8 +0,0 @@
-# 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.