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

rocco 0.2 → 0.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

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