RubyGems - rocco - Versions diffs - 0.2 → 0.3 - Mend

rocco 0.2 → 0.3

Files changed (8) hide show

data/Rakefile CHANGED

@@ -22,7 +22,7 @@ end
 # Bring in Rocco tasks
 require 'rocco/tasks'
-Rocco::make 'docs/'
+Rocco::make 'docs/', FileList['lib/**/*.rb', 'bin/rocco']
 desc 'Build rocco docs'
 task :docs => :rocco

data/bin/rocco CHANGED

@@ -1,6 +1,54 @@
 #!/usr/bin/env ruby
-libdir = File.expand_path('../../lib', __FILE__).sub(/^#{Dir.pwd}\//, '')
+# The `rocco(1)` executable.
+#
+# This isn't documented yet.
+#
+#/ Usage: rocco [-o <dir>] <file>...
+#/ Generate literate-programming-style documentation for Ruby source <file>s.
+#/
+#/ Options:
+#/   -o, --output=<dir>   Directory where generated HTML files are written
+#/
+#/       --help           Show this help message
+require 'optparse'
+# Write usage message to stdout and exit.
+def usage(stream=$stderr, status=1)
+  stream.puts File.read(__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 = []
+ARGV.options { |o|
+  o.program_name = File.basename($0)
+  o.on("-o", "--output=DIR") { |dir| output_dir = dir }
+  o.on_tail("-h", "--help") { usage($stdout, 0) }
+  o.parse!
+} or abort_with_note
+# 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'
@@ -27,9 +75,13 @@ rescue LoadError
   raise
 end
-ARGV.each do |filename|
-  rocco = Rocco.new(filename)
-  dest = File.basename(filename, '.rb') + '.html'
-  warn "rocco: #{filename} -> #{dest}"
+# Create the output directory if it doesn't already exist.
+Dir.mkdir output_dir if !File.directory?(output_dir)
+# Run each file through Rocco and write output.
+sources.each do |filename|
+  rocco = Rocco.new(filename, sources)
+  dest = File.join(output_dir, File.basename(filename, '.rb') + '.html')
+  puts "rocco: #{filename} -> #{dest}"
   File.open(dest, 'wb') { |fd| fd.write(rocco.to_html) }
 end

data/lib/rocco.rb CHANGED

@@ -56,14 +56,14 @@ 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.
+# `Rocco.new` takes a source `filename`, an optional list of source filenames
+# for other documentation sources, 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.2'
+  VERSION = '0.3'
-  def initialize(filename, &block)
+  def initialize(filename, sources=[], &block)
     @file = filename
     @data =
       if block_given?
@@ -71,6 +71,7 @@ class Rocco
       else
         File.read(filename)
       end
+    @sources = sources
     @sections = highlight(split(parse(@data)))
   end
@@ -83,6 +84,10 @@ class Rocco
   # 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
   # Generate HTML output for the entire document.
   require 'rocco/layout'
   def to_html
@@ -99,7 +104,7 @@ class Rocco
     docs, code = [], []
     data.split("\n").each do |line|
       case line
-      when /^\s*#/
+      when /^\s*#(?:\s+|$)/
         if code.any?
           sections << [docs, code]
           docs, code = [], []

data/lib/rocco/layout.mustache CHANGED

@@ -8,6 +8,18 @@
 <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>

data/lib/rocco/layout.rb CHANGED

@@ -21,4 +21,18 @@ class Rocco::Layout < Mustache
       }
     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, '.rb') + '.html'
+      }
+    end
+  end
 end

data/lib/rocco/tasks.rb CHANGED

@@ -92,7 +92,7 @@ class Rocco
       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)
+        rocco = Rocco.new(source_file, @sources.to_a)
         File.open(dest_file, 'wb') { |fd| fd.write(rocco.to_html) }
       end
       task @name => dest_file

data/rocco.gemspec CHANGED

@@ -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.2'
-  s.date = '2010-03-11'
+  s.version = '0.3'
+  s.date = '2010-03-16'
   s.description = "Docco in Ruby"
   s.summary     = s.description

metadata CHANGED

@@ -4,8 +4,8 @@ version: !ruby/object:Gem::Version
   prerelease: false
   segments:
   - 0
-  - 2
-  version: "0.2"
+  - 3
+  version: "0.3"
 platform: ruby
 authors:
 - Ryan Tomayko
@@ -13,7 +13,7 @@ autorequire:
 bindir: bin
 cert_chain: []
-date: 2010-03-11 00:00:00 -08:00
+date: 2010-03-16 00:00:00 -07:00
 default_executable:
 dependencies:
 - !ruby/object:Gem::Dependency