rocco 0.5 → 0.6

data/CHANGES.md

@@ -0,0 +1,63 @@
+CHANGES
+=======
+
+0.6 (2011-03-05)
+----------------
+
+This release brought to you almost entirely
+by [mikewest](http://github.com/mikewest).
+
+### Features
+
+* Added `-t`/`--template` CLI option that allows you to specify a Mustache
+  template that ought be used when rendering the final documentation.
+  (Issue #16)
+
+* More variables in templates:
+  * `docs?`:    True if `docs` contains text of any sort, False if it's empty.
+  * `code?`:    True if `code` contains text of any sort, False if it's empty.
+  * `empty?`:   True if both `code` and `docs` are empty.  False otherwise.
+  * `header?`:  True if `docs` contains _only_ a HTML header.  False otherwise.
+
+* Test suite!  (Run `rake test`)
+
+* Autodetect file's language if Pygments is installed locally (Issue #19)
+
+* Autopopulate comment characters for known languages (Issue #20)
+
+* Correctly parse block comments (Issue #22)
+
+* Stripping encoding definitions from Ruby and Python files in the same
+  way we strip shebang lines (Issue #21)
+
+* Adjusting section IDs to contain descriptive test from headers.  A header
+  section's ID might be `section-Header_text_goes_here` for friendlier URLs.
+  Other section IDs will remain the same (`section-2` will stay
+  `section-2`). (Issue #28)
+
+### Bugs Fixed
+
+* Docco's CSS changed: we updated Rocco's HTML accordingly, and pinned
+  the CSS file to Docco's 0.3.0 tag.  (Issues #12 and #23)
+
+* Fixed code highlighting for shell scripts (among others) (Issue #13)
+
+* Fixed buggy regex for comment char stripping (Issue #15)
+
+* Specifying UTF-8 encoding for Pygments (Issue #10)
+
+* Extensionless file support (thanks to [Vasily Polovnyov][vast] for the
+  fix!) (Issue #24)
+
+* Fixing language support for Pygments webservice (Issue #11)
+
+* The source jumplist now generates correctly relative URLs (Issue #26)
+
+* Fixed an issue with using mustache's `template_path=` incorrectly.
+
+[vast]: https://github.com/vast
+
+0.5
+---
+
+Rocco 0.5 emerged from the hazy mists, complete and unfettered by history.

data/Rakefile

@@ -3,7 +3,7 @@ $LOAD_PATH.unshift 'lib'
 require 'rake/testtask'
 require 'rake/clean'
 
-task :default => [:sup, :docs]
+task :default => [:sup, :docs, :test]
 
 desc 'Holla'
 task :sup do
@@ -16,7 +16,7 @@ end
 
 desc 'Run tests (default)'
 Rake::TestTask.new(:test) do |t|
-  t.test_files = FileList['test/*_test.rb']
+  t.test_files = FileList['test/suite.rb']
   t.ruby_opts = ['-rubygems'] if defined? Gem
 end
 
@@ -30,12 +30,12 @@ directory 'docs/'
 
 desc 'Build docs and open in browser for the reading'
 task :read => :docs do
-  sh 'open docs/rocco.html'
+  sh 'open docs/lib/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
+file 'docs/index.html' => 'docs/lib/rocco.html' do |f|
+  cp 'docs/lib/rocco.html', 'docs/index.html', :preserve => true
 end
 task :docs => 'docs/index.html'
 CLEAN.include 'docs/index.html'

data/bin/rocco

@@ -7,6 +7,7 @@
 #/   -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'
@@ -37,6 +38,7 @@ ARGV.options { |o|
   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
@@ -88,7 +90,8 @@ 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')
+  dest = filename.sub(Regexp.new("#{File.extname(filename)}$"),".html")
+  dest = File.join(output_dir, dest) if output_dir != '.'
   puts "rocco: #{filename} -> #{dest}"
   FileUtils.mkdir_p File.dirname(dest)
   File.open(dest, 'wb') { |fd| fd.write(rocco.to_html) }

data/lib/rocco.rb

@@ -61,37 +61,82 @@ end
 
 # `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 two members: `:language`, which specifies which
-# Pygments lexer to use; and `:comment_chars`, which specifies the comment
-# characters of the target language. The options default to `'ruby'` and `'#'`,
-# respectively.
-# 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.
+# 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'
+  VERSION = '0.6'
 
   def initialize(filename, sources=[], options={}, &block)
-    @file = filename
+    @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)
-    @sources = sources
-    @comment_pattern = Regexp.new("^\\s*#{@options[:comment_chars]}")
+
+    # If we detect a language
+    if detect_language() != "text"
+      # then assign the detected language to `:language`, and look for
+      # comment characters based on that language
+      @options[:language] = detect_language()
+      @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()
+
+    # If neither is true, then convert the default comment character string
+    # into the comment_char syntax (we'll discuss that syntax in detail when
+    # we get to `generate_comment_chars()` in a moment.
+    else
+      @options[:comment_chars] = {
+        :single => @options[:comment_chars],
+        :multi => nil
+      }
+    end
+
+    # Turn `:comment_chars` into a regex matching a series of spaces, the
+    # `:comment_chars` string, and the an optional space.  We'll use that
+    # to detect single-line comments.
+    @comment_pattern =
+      Regexp.new("^\\s*#{@options[:comment_chars][:single]}\s?")
+
+    # `parse()` the file contents stored in `@data`.  Run the result through
+    # `split()` and that result through `highlight()` to generate the final
+    # section list.
     @sections = highlight(split(parse(@data)))
   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,
@@ -105,34 +150,207 @@ class Rocco
   # Generate HTML output for the entire document.
   require 'rocco/layout'
   def to_html
-    Rocco::Layout.new(self).render
+    Rocco::Layout.new(self, @options[:template_file]).render
+  end
+
+  # Helper Functions
+  # ----------------
+
+  # Returns `true` if `pygmentize` is available locally, `false` otherwise.
+  def pygmentize?
+    @_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 ||=
+      if pygmentize?
+        %x[pygmentize -N #{@file}].strip!
+      else
+        "text"
+      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][: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.
+  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 => "*/" }
+    },
+    "css"           =>  {
+      :single => nil,
+      :multi  => { :start => "/**", :middle => "*", :end => "*/" }
+    },
+    "java"          =>  {
+      :single => "//",
+      :multi  => { :start => "/**", :middle => "*", :end => "*/" }
+    },
+    "js"            =>  {
+      :single => "//",
+      :multi  => { :start => "/**", :middle => "*", :end => "*/" }
+    },
+    "lua"           =>  {
+      :single => "--",
+      :multi => nil
+    },
+    "python"        =>  {
+      :single => "#",
+      :multi  => { :start => '"""', :middle => nil, :end => '"""' }
+    },
+    "rb"            =>  {
+      :single => "#",
+      :multi  => { :start => '=begin', :middle => nil, :end => '=end' }
+    },
+    "scheme"        =>  { :single => ";;",  :multi => nil },
+  }
+
+  def generate_comment_chars
+    @_commentchar ||=
+      if COMMENT_STYLES[@options[:language]]
+        COMMENT_STYLES[@options[:language]]
+      else
+        { :single => @options[:comment_chars], :multi => nil }
+      end
   end
 
-  #### Internal Parsing and Highlighting
+  # 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.
+  # raw lines parsed from the input file, comment characters stripped.
   def parse(data)
     sections = []
     docs, code = [], []
     lines = data.split("\n")
+
+    # The first line is ignored if it is a shebang line.  We also ignore the
+    # PEP 263 encoding information in python sourcefiles, and the similar ruby
+    # 1.9 syntax.
     lines.shift if lines[0] =~ /^\#\!/
+    lines.shift if lines[0] =~ /coding[:=]\s*[-\w.]+/ &&
+                   [ "python", "rb" ].include?(@options[:language])
+
+    # To detect both block comments and single-line comments, we'll set
+    # up a tiny state machine, and loop through each line of the file.
+    # This requires an `in_comment_block` boolean, and a few regular
+    # expressions for line tests.
+    in_comment_block = false
+    single_line_comment, block_comment_start, block_comment_mid, block_comment_end =
+      nil, nil, nil, nil
+    if not @options[:comment_chars][:single].nil?
+      single_line_comment = Regexp.new("^\\s*#{Regexp.escape(@options[:comment_chars][:single])}\\s?")
+    end
+    if not @options[:comment_chars][:multi].nil?
+      block_comment_start = Regexp.new("^\\s*#{Regexp.escape(@options[:comment_chars][:multi][:start])}\\s*$")
+      block_comment_end   = Regexp.new("^\\s*#{Regexp.escape(@options[:comment_chars][:multi][:end])}\\s*$")
+      if @options[:comment_chars][:multi][:middle]
+        block_comment_mid = Regexp.new("^\\s*#{Regexp.escape(@options[:comment_chars][:multi][:middle])}\\s?")
+      end
+    end
     lines.each do |line|
-      case line
-      when @comment_pattern
-        if code.any?
-          sections << [docs, code]
-          docs, code = [], []
+      # If we're currently in a comment block, check whether the line matches
+      # the _end_ of a comment block.
+      if in_comment_block
+        if block_comment_end && line.match( block_comment_end )
+          in_comment_block = false
+        else
+          docs << line.sub( block_comment_mid || '', '' )
         end
-        docs << line
+      # Otherwise, check whether the line matches the beginning of a block, or
+      # a single-line comment all on it's lonesome.  In either case, if there's
+      # code, start a new section
       else
-        code << line
+        if block_comment_start && line.match( block_comment_start )
+          in_comment_block = true
+          if code.any?
+            sections << [docs, code]
+            docs, code = [], []
+          end
+        elsif single_line_comment && line.match( single_line_comment )
+          if code.any?
+            sections << [docs, code]
+            docs, code = [], []
+          end
+          docs << line.sub( single_line_comment || '', '' )
+        else
+          code << line
+        end
       end
     end
     sections << [docs, code] if docs.any? || code.any?
-    sections
+    normalize_leading_spaces( sections )
+  end
+
+  # Normalizes documentation whitespace by checking for leading whitespace,
+  # removing it, and then removing the same amount of whitespace from each
+  # succeeding line.  That is:
+  #
+  #     def func():
+  #       """
+  #         Comment 1
+  #         Comment 2
+  #       """
+  #       print "omg!"
+  #
+  # should yield a comment block of `Comment 1\nComment 2` and code of
+  # `def func():\n  print "omg!"`
+  def normalize_leading_spaces( sections )
+    sections.map do |section|
+      if section.any? && section[0].any?
+        leading_space = section[0][0].match( "^\s+" )
+        if leading_space
+          section[0] =
+            section[0].map{ |line| line.sub( /^#{leading_space.to_s}/, '' ) }
+        end
+      end
+      section
+    end
   end
 
   # Take the list of paired *sections* two-tuples and split into two
@@ -141,7 +359,7 @@ class Rocco
   def split(sections)
     docs_blocks, code_blocks = [], []
     sections.each do |docs,code|
-      docs_blocks << docs.map { |line| line.sub(@comment_pattern, '') }.join("\n")
+      docs_blocks << docs.join("\n")
       code_blocks << code.map do |line|
         tabs = line.match(/^(\t+)/)
         tabs ? line.sub(/^\t+/, '  ' * tabs.captures[0].length) : line
@@ -163,20 +381,50 @@ class Rocco
       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 ENV['PATH'].split(':').any? { |dir| executable?("#{dir}/pygmentize") }
-      code_html = highlight_pygmentize(code_stream)
-    else 
-      code_html = highlight_webservice(code_stream)
+    # Combine all code blocks into a single big stream with section dividers and
+    # run through either `pygmentize(1)` or <http://pygments.appspot.com>
+    span, espan = '<span class="c.?">', '</span>'
+    if @options[:comment_chars][:single]
+      front = @options[:comment_chars][:single]
+      divider_input  = "\n\n#{front} DIVIDER\n\n"
+      divider_output = Regexp.new(
+        [ "\\n*",
+          span,
+          Regexp.escape(front),
+          ' DIVIDER',
+          espan,
+          "\\n*"
+        ].join, Regexp::MULTILINE
+      )
+    else
+      front = @options[:comment_chars][:multi][:start]
+      back  = @options[:comment_chars][:multi][:end]
+      divider_input  = "\n\n#{front}\nDIVIDER\n#{back}\n\n"
+      divider_output = Regexp.new(
+        [ "\\n*",
+          span, Regexp.escape(front), espan,
+          "\\n",
+          span, "DIVIDER", espan,
+          "\\n",
+          span, Regexp.escape(back), espan,
+          "\\n*"
+        ].join, Regexp::MULTILINE
+      )
     end
 
+    code_stream = code_blocks.join( divider_input )
+
+    code_html =
+      if pygmentize?
+        highlight_pygmentize(code_stream)
+      else
+        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).
+      split(divider_output).
       map { |code| code.sub(/\n?<div class="highlight"><pre>/m, '') }.
       map { |code| code.sub(/\n?<\/pre><\/div>\n/m, '') }
 
@@ -188,7 +436,7 @@ class Rocco
   # then fork off a child process to write the input.
   def highlight_pygmentize(code)
     code_html = nil
-    open("|pygmentize -l #{@options[:language]} -f html", 'r+') do |fd|
+    open("|pygmentize -l #{@options[:language]} -O encoding=utf-8 -f html", 'r+') do |fd|
       pid =
         fork {
           fd.close_read
@@ -204,13 +452,13 @@ class Rocco
 
     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}
+      {'lang' => @options[:language], 'code' => code}
     ).body
   end
 end

data/lib/rocco/layout.mustache

@@ -3,7 +3,7 @@
 <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">
+  <link rel="stylesheet" href="http://github.com/jashkenas/docco/raw/0.3.0/resources/docco.css">
 </head>
 <body>
 <div id='container'>
@@ -29,10 +29,10 @@
   </thead>
   <tbody>
     {{#sections}}
-    <tr id='section-{{ num }}'>
+    <tr id='section-{{ section_id }}'>
       <td class=docs>
-        <div class="octowrap">
-          <a class="octothorpe" href="#section-{{ num }}">#</a>
+        <div class="pilwrap">
+          <a class="pilcrow" href="#section-{{ section_id }}">&#182;</a>
         </div>
         {{{ docs }}}
       </td>

data/lib/rocco/layout.rb

@@ -1,10 +1,14 @@
 require 'mustache'
+require 'pathname'
 
 class Rocco::Layout < Mustache
-  self.template_path = File.dirname(__FILE__)
+  self.template_path = "#{File.dirname(__FILE__)}/.."
 
-  def initialize(doc)
+  def initialize(doc, file=nil)
     @doc = doc
+    if not file.nil?
+      Rocco::Layout.template_file = file
+    end
   end
 
   def title
@@ -14,10 +18,19 @@ class Rocco::Layout < Mustache
   def sections
     num = 0
     @doc.sections.map do |docs,code|
+      is_header = /^<h.>(.+)<\/h.>$/.match( docs )
+      header_text = is_header && is_header[1].split.join("_")
+      num += 1
       {
-        :docs  => docs,
-        :code  => code,
-        :num   => (num += 1)
+        :docs       =>  docs,
+        :docs?      =>  !docs.empty?,
+        :header?    =>  is_header,
+
+        :code       =>  code,
+        :code?      =>  !code.empty?,
+
+        :empty?     =>  ( code.empty? && docs.empty? ),
+        :section_id =>  is_header ? header_text : num
       }
     end
   end
@@ -27,11 +40,14 @@ class Rocco::Layout < Mustache
   end
 
   def sources
+    currentpath = Pathname.new( File.dirname( @doc.file ) )
     @doc.sources.sort.map do |source|
+      htmlpath = Pathname.new( source.sub( Regexp.new( "#{File.extname(source)}$"), ".html" ) )
+
       {
-        :path => source,
-        :basename => File.basename(source),
-        :url => File.basename(source).split('.')[0..-2].join('.') + '.html'
+        :path       => source,
+        :basename   => File.basename(source),
+        :url        => htmlpath.relative_path_from( currentpath )
       }
     end
   end

data/lib/rocco/tasks.rb

@@ -70,7 +70,7 @@ class Rocco
       # 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'
+        dest_file = source_file.sub(Regexp.new("#{File.extname(source_file)}$"), ".html")
         define_file_task source_file, "#{@dest}#{dest_file}"
 
         # If `rake/clean` was required, add the generated files to the list.
@@ -103,6 +103,7 @@ class Rocco
       file dest_file => prerequisites do |f|
         verbose { puts "rocco: #{source_file} -> #{dest_file}" }
         rocco = Rocco.new(source_file, @sources.to_a, @options)
+        FileUtils.mkdir_p(File.dirname(dest_file))
         File.open(dest_file, 'wb') { |fd| fd.write(rocco.to_html) }
       end
       task @name => dest_file

data/rocco.gemspec

@@ -3,17 +3,18 @@ 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.5'
-  s.date = '2010-09-10'
+  s.version = '0.6'
+  s.date = '2011-03-05'
 
   s.description = "Docco in Ruby"
   s.summary     = s.description
 
-  s.authors = ["Ryan Tomayko"]
-  s.email = "r@tomayko.com"
+  s.authors = ["Ryan Tomayko", "Mike West"]
+  s.email   = ["r@tomayko.com", "<mike@mikewest.org>"]
 
   # = MANIFEST =
   s.files = %w[
+    CHANGES.md
     COPYING
     README
     Rakefile
@@ -23,6 +24,19 @@ Gem::Specification.new do |s|
     lib/rocco/layout.rb
     lib/rocco/tasks.rb
     rocco.gemspec
+    test/fixtures/issue10.iso-8859-1.rb
+    test/fixtures/issue10.utf-8.rb
+    test/helper.rb
+    test/suite.rb
+    test/test_basics.rb
+    test/test_block_comments.rb
+    test/test_comment_normalization.rb
+    test/test_commentchar_detection.rb
+    test/test_descriptive_section_names.rb
+    test/test_language_detection.rb
+    test/test_reported_issues.rb
+    test/test_skippable_lines.rb
+    test/test_source_list.rb
   ]
   # = MANIFEST =
 

data/test/fixtures/issue10.iso-8859-1.rb

@@ -0,0 +1 @@
+# hello w�rld

data/test/fixtures/issue10.utf-8.rb

@@ -0,0 +1 @@
+# hello ąćęłńóśźż

data/test/helper.rb

@@ -0,0 +1,20 @@
+rootdir = File.expand_path('../../lib', __FILE__)
+$LOAD_PATH.unshift "#{rootdir}/lib"
+
+require 'test/unit'
+begin; require 'turn'; rescue LoadError; end
+begin
+  require 'rdiscount'
+rescue LoadError
+  if !defined?(Gem)
+    require 'rubygems'
+    retry
+  end
+end
+require 'rocco'
+
+def roccoize( filename, contents, options = {} )
+  Rocco.new( filename, [ filename ], options ) {
+    contents
+  }
+end

data/test/suite.rb

@@ -0,0 +1,5 @@
+require File.expand_path('../helper', __FILE__)
+require 'test/unit'
+
+Dir[File.expand_path('../test_*.rb', __FILE__)].
+each { |file| require file }

data/test/test_basics.rb

@@ -0,0 +1,63 @@
+require File.expand_path('../helper', __FILE__)
+
+class RoccoBasicTests < Test::Unit::TestCase
+  def test_rocco_exists_and_is_instancable
+    roccoize( "filename.rb", "# Comment 1\ndef codeblock\nend\n" )
+  end
+
+  def test_filename
+    r = roccoize( "filename.rb", "# Comment 1\ndef codeblock\nend\n" )
+    assert_equal "filename.rb", r.file
+  end
+
+  def test_sources
+    r = roccoize( "filename.rb", "# Comment 1\ndef codeblock\nend\n" )
+    assert_equal [ "filename.rb" ], r.sources
+  end
+
+  def test_sections
+    r = roccoize( "filename.rb", "# Comment 1\ndef codeblock\nend\n" )
+    assert_equal 1, r.sections.length
+    assert_equal 2, r.sections[ 0 ].length
+    assert_equal "<p>Comment 1</p>\n", r.sections[ 0 ][ 0 ]
+    assert_equal "<span class=\"k\">def</span> <span class=\"nf\">codeblock</span>\n<span class=\"k\">end</span>", r.sections[ 0 ][ 1 ]
+  end
+
+  def test_parsing
+    r = Rocco.new( 'test' ) { "" } # Generate throwaway instance so I can test `parse`
+    assert_equal(
+      [
+        [ [ "Comment 1" ], [ "def codeblock", "end" ] ]
+      ],
+      r.parse( "# Comment 1\ndef codeblock\nend\n" )
+    )
+    assert_equal(
+      [
+        [ [ "Comment 1" ], [ "def codeblock" ] ],
+        [ [ "Comment 2" ], [ "end" ] ]
+      ],
+      r.parse( "# Comment 1\ndef codeblock\n# Comment 2\nend\n" )
+    )
+  end
+
+  def test_splitting
+    r = Rocco.new( 'test' ) { "" } # Generate throwaway instance so I can test `split`
+    assert_equal(
+      [
+        [ "Comment 1" ],
+        [ "def codeblock\nend" ]
+      ],
+      r.split([ [ [ "Comment 1" ], [ "def codeblock", "end" ] ] ])
+    )
+    assert_equal(
+      [
+        [ "Comment 1", "Comment 2" ],
+        [ "def codeblock", "end" ]
+      ],
+      r.split( [
+        [ [ "Comment 1" ], [ "def codeblock" ] ],
+        [ [ "Comment 2" ], [ "end" ] ]
+      ] )
+    )
+  end
+end

data/test/test_block_comments.rb

@@ -0,0 +1,101 @@
+require File.expand_path('../helper', __FILE__)
+
+class RoccoBlockCommentTest < Test::Unit::TestCase
+  def test_basics
+    r = Rocco.new( 'test', '', { :language => "c" } ) { "" } # Generate throwaway instance so I can test `parse`
+    assert_equal(
+      [
+        [ [ "Comment 1" ], [ "def codeblock", "end" ] ]
+      ],
+      r.parse( "/**\n * Comment 1\n */\ndef codeblock\nend\n" )
+    )
+    assert_equal(
+      [
+        [ [ "Comment 1a", "Comment 1b" ], [ "def codeblock", "end" ] ]
+      ],
+      r.parse( "/**\n * Comment 1a\n * Comment 1b\n */\ndef codeblock\nend\n" )
+    )
+  end
+
+  def test_multiple_blocks
+    r = Rocco.new( 'test', '', { :language => "c" } ) { "" } # Generate throwaway instance so I can test `parse`
+    assert_equal(
+      [
+        [ [ "Comment 1" ], [ "def codeblock", "end" ] ],
+        [ [ "Comment 2" ], [] ]
+      ],
+      r.parse( "/**\n * Comment 1\n */\ndef codeblock\nend\n/**\n * Comment 2\n */\n" )
+    )
+    assert_equal(
+      [
+        [ [ "Comment 1" ], [ "def codeblock", "end" ] ],
+        [ [ "Comment 2" ], [ "if false", "end" ] ]
+      ],
+      r.parse( "/**\n * Comment 1\n */\ndef codeblock\nend\n/**\n * Comment 2\n */\nif false\nend" )
+    )
+  end
+
+  def test_block_without_middle_character
+    r = Rocco.new( 'test', '', { :language => "python" } ) { "" } # Generate throwaway instance so I can test `parse`
+    assert_equal(
+      [
+        [ [ "Comment 1" ], [ "def codeblock", "end" ] ],
+        [ [ "Comment 2" ], [] ]
+      ],
+      r.parse( "\"\"\"\n  Comment 1\n\"\"\"\ndef codeblock\nend\n\"\"\"\n  Comment 2\n\"\"\"\n" )
+    )
+    assert_equal(
+      [
+        [ [ "Comment 1" ], [ "def codeblock", "end" ] ],
+        [ [ "Comment 2" ], [ "if false", "end" ] ]
+      ],
+      r.parse( "\"\"\"\n  Comment 1\n\"\"\"\ndef codeblock\nend\n\"\"\"\n  Comment 2\n\"\"\"\nif false\nend" )
+    )
+  end
+
+  def test_language_without_single_line_comments_parse
+    r = Rocco.new( 'test', '', { :language => "css" } ) { "" } # Generate throwaway instance so I can test `parse`
+    assert_equal(
+      [
+        [ [ "Comment 1" ], [ "def codeblock", "end" ] ],
+        [ [ "Comment 2" ], [ "if false", "end" ] ]
+      ],
+      r.parse( "/**\n * Comment 1\n */\ndef codeblock\nend\n/**\n * Comment 2\n */\nif false\nend" )
+    )
+  end
+
+  def test_language_without_single_line_comments_split
+    r = Rocco.new( 'test', '', { :language => "css" } ) { "" } # Generate throwaway instance so I can test `parse`
+    assert_equal(
+      [
+        [ "Comment 1", "Comment 2" ],
+        [ "def codeblock\nend", "if false\nend" ]
+      ],
+      r.split( [
+        [ [ "Comment 1" ], [ "def codeblock", "end" ] ],
+        [ [ "Comment 2" ], [ "if false", "end" ] ]
+      ] )
+    )
+  end
+
+  def test_language_without_single_line_comments_highlight
+    r = Rocco.new( 'test', '', { :language => "css" } ) { "" } # Generate throwaway instance so I can test `parse`
+
+    highlighted = r.highlight( r.split( r.parse( "/**\n * This is a comment!\n */\n.rule { goes: here; }\n/**\n * Comment 2\n */\n.rule2 { goes: here; }" ) ) )
+    assert_equal(
+      "<p>This is a comment!</p>",
+      highlighted[0][0]
+    )
+    assert_equal(
+      "<p>Comment 2</p>\n",
+      highlighted[1][0]
+    )
+    assert(
+      !highlighted[0][1].include?("DIVIDER") &&
+      !highlighted[1][1].include?("DIVIDER"),
+      "`DIVIDER` stripped successfully."
+    )
+    assert( true )
+  end
+
+end

data/test/test_comment_normalization.rb

@@ -0,0 +1,25 @@
+require File.expand_path('../helper', __FILE__)
+
+class RoccoCommentNormalization < Test::Unit::TestCase
+  def test_normal_comments
+    r = Rocco.new( 'test', '', { :language => "python" } ) { "" } # Generate throwaway instance so I can test `parse`
+    assert_equal(
+      [
+          [ [ "Comment 1a", "Comment 1b" ], [ "def codeblock", "end" ] ],
+          [ [ "Comment 2a", "  Comment 2b" ], [] ]
+      ],
+      r.parse( "\"\"\"\n  Comment 1a\n  Comment 1b\n\"\"\"\ndef codeblock\nend\n\"\"\"\n  Comment 2a\n    Comment 2b\n\"\"\"\n" )
+    )
+  end
+
+  def test_single_line_comments
+    r = Rocco.new( 'test', '', { :language => "python" } ) { "" } # Generate throwaway instance so I can test `parse`
+    assert_equal(
+      [
+          [ [ "Comment 1a", "Comment 1b" ], [ "def codeblock", "end" ] ],
+          [ [ "Comment 2a", "  Comment 2b" ], [] ]
+      ],
+      r.parse( "#   Comment 1a\n#   Comment 1b\ndef codeblock\nend\n#   Comment 2a\n#     Comment 2b\n" )
+    )
+  end
+end

data/test/test_commentchar_detection.rb

@@ -0,0 +1,28 @@
+require File.expand_path('../helper', __FILE__)
+
+class RoccoAutomaticCommentChars < Test::Unit::TestCase
+  def test_basic_detection
+    r = Rocco.new( 'filename.js' ) { "" }
+    assert_equal "//", r.options[:comment_chars][:single]
+  end
+
+  def test_fallback_language
+    r = Rocco.new( 'filename.an_extension_with_no_meaning_whatsoever', '', { :language => "js" } ) { "" }
+    assert_equal "//", r.options[:comment_chars][:single]
+  end
+
+  def test_fallback_default
+    r = Rocco.new( 'filename.an_extension_with_no_meaning_whatsoever' ) { "" }
+    assert_equal "#", r.options[:comment_chars][:single], "`:comment_chars` should be `#` when falling back to defaults."
+  end
+
+  def test_fallback_user
+    r = Rocco.new( 'filename.an_extension_with_no_meaning_whatsoever', '', { :comment_chars => "user" } ) { "" }
+    assert_equal "user", r.options[:comment_chars][:single], "`:comment_chars` should be the user's default when falling back to user-provided settings."
+  end
+
+  def test_fallback_user_with_unknown_language
+    r = Rocco.new( 'filename.an_extension_with_no_meaning_whatsoever', '', { :language => "not-a-language", :comment_chars => "user" } ) { "" }
+    assert_equal "user", r.options[:comment_chars][:single], "`:comment_chars` should be the user's default when falling back to user-provided settings."
+  end
+end

data/test/test_descriptive_section_names.rb

@@ -0,0 +1,30 @@
+require File.expand_path('../helper', __FILE__)
+
+class RoccoDescriptiveSectionNamesTests < Test::Unit::TestCase
+  def test_section_name
+    r = roccoize( "filename.rb", "# # Comment 1\ndef codeblock\nend\n" )
+    html = r.to_html
+    assert(
+      html.include?( "<tr id='section-Comment_1'>" ),
+      "The first section should be named"
+    )
+    assert(
+      html.include?( '<a class="pilcrow" href="#section-Comment_1">' ),
+      "The rendered HTML should link to a named section"
+    )
+  end
+
+  def test_section_numbering
+    r = roccoize( "filename.rb", "# # Header 1\ndef codeblock\nend\n# Comment 1\ndef codeblock1\nend\n# # Header 2\ndef codeblock2\nend" )
+    html = r.to_html
+    assert(
+      html.include?( '<a class="pilcrow" href="#section-Header_1">' ) &&
+      html.include?( '<a class="pilcrow" href="#section-Header_2">' ),
+      "First and second headers should be named sections"
+    )
+    assert(
+      html.include?( '<a class="pilcrow" href="#section-2">' ),
+      "Sections should continue numbering as though headers were counted."
+    )
+  end
+end

data/test/test_language_detection.rb

@@ -0,0 +1,27 @@
+require File.expand_path('../helper', __FILE__)
+
+class RoccoLanguageDetection < Test::Unit::TestCase
+  def test_basic_detection
+    r = Rocco.new( 'filename.py' ) { "" }
+    if r.pygmentize?
+      assert_equal "python", r.detect_language(), "`detect_language()` should return the correct language"
+      assert_equal "python", r.options[:language], "`@options[:language]` should be set to the correct language"
+    end
+  end
+
+  def test_fallback_default
+    r = Rocco.new( 'filename.an_extension_with_no_meaning_whatsoever' ) { "" }
+    if r.pygmentize?
+      assert_equal "text", r.detect_language(), "`detect_language()` should return `text` when nothing else is detected"
+      assert_equal "ruby", r.options[:language], "`@options[:language]` should be set to `ruby` when nothing else is detected"
+    end
+  end
+
+  def test_fallback_user
+    r = Rocco.new( 'filename.an_extension_with_no_meaning_whatsoever', '', { :language => "c" } ) { "" }
+    if r.pygmentize?
+      assert_equal "text", r.detect_language(), "`detect_language()` should return `text` nothing else is detected"
+      assert_equal "c", r.options[:language], "`@options[:language]` should be set to the user's setting when nothing else is detected"
+    end
+  end
+end

data/test/test_reported_issues.rb

@@ -0,0 +1,86 @@
+# encoding: utf-8
+require File.expand_path('../helper', __FILE__)
+
+class RoccoIssueTests < Test::Unit::TestCase
+  def test_issue07_incorrect_parsing_in_c_mode
+    # Precursor to issue #13 below, Rocco incorrectly parsed C/C++
+    # http://github.com/rtomayko/rocco/issues#issue/7
+    r = Rocco.new( 'issue7.c', [], { :language => 'c' } ) {
+        "// *stdio.h* declares *puts*\n#include <stdio.h>\n\n//### code hello world\n\n// every C program contains function *main*.\nint main (int argc, char *argv[]) {\n  puts('hello world');\n  return 0;\n}\n\n// that's it!"
+    }
+    r.sections.each do | section |
+      if not section[1].nil?
+        assert(
+            !section[1].include?("<span class=\"c\"># DIVIDER</span>"),
+            "`# DIVIDER` present in code text, which means the highligher screwed up somewhere."
+        )
+      end
+    end
+  end
+
+  def test_issue10_utf8_processing
+    # Rocco has issues with strange UTF-8 characters: need to explicitly set the encoding for Pygments
+    # http://github.com/rtomayko/rocco/issues#issue/10
+    r = Rocco.new( File.dirname(__FILE__) + "/fixtures/issue10.utf-8.rb" )
+    assert_equal(
+      "<p>hello ąćęłńóśźż</p>\n",
+      r.sections[0][0],
+      "UTF-8 input files ought behave correctly."
+    )
+    # and, just for grins, ensure that iso-8859-1 works too.
+    # @TODO:    Is this really the correct behavior?  Converting text
+    #           to UTF-8 on the way out is probably preferable.
+    r = Rocco.new( File.dirname(__FILE__) + "/fixtures/issue10.iso-8859-1.rb" )
+    assert_equal(
+      "<p>hello w\366rld</p>\n",
+      r.sections[0][0],
+      "ISO-8859-1 input should probably also behave correctly."
+    )
+  end
+
+  def test_issue12_css_octothorpe_classname_change
+    # Docco changed some CSS classes.  Rocco needs to update its default template.
+    # http://github.com/rtomayko/rocco/issues#issue/12
+    r = Rocco.new( 'issue12.sh' ) {
+      "# Comment 1\n# Comment 1\nprint 'omg!'"
+    }
+    html = r.to_html
+    assert(
+      !html.include?( "<div class=\"octowrap\">" ),
+      "`octowrap` wrapper is present in rendered HTML.  This ought be replaced with `pilwrap`."
+    )
+    assert(
+      !html.include?( "<a class=\"octothorpe\" href=\"#section-1\">" ),
+      "`octothorpe` link is present in rendered HTML.  This ought be replaced with `pilcrow`."
+    )
+  end
+
+  def test_issue13_incorrect_code_divider_parsing
+    # In `bash` mode (among others), the comment class is `c`, not `c1`.
+    # http://github.com/rtomayko/rocco/issues#issue/13
+    r = Rocco.new( 'issue13.sh', [], { :language => 'bash' } ) {
+      "# Comment 1\necho 'code';\n# Comment 2\necho 'code';\n# Comment 3\necho 'code';\n"
+    }
+    r.sections.each do | section |
+      if not section[1].nil?
+        assert(
+          !section[1].include?("<span class=\"c\"># DIVIDER</span>"),
+          "`# DIVIDER` present in code text, which means the highligher screwed up somewhere."
+        )
+      end
+    end
+  end
+
+  def test_issue15_extra_space_after_comment_character_remains
+    # After the comment character, a single space should be removed.
+    # http://github.com/rtomayko/rocco/issues#issue/15
+    r = Rocco.new( 'issue15.sh') {
+      "# Comment 1\n# ---------\necho 'code';"
+    }
+    assert(
+      !r.sections[0][0].include?( "<hr />" ),
+      "`<hr />` present in rendered documentation text.  It should be a header, not text followed by a horizontal rule."
+    )
+    assert_equal("<h2>Comment 1</h2>\n", r.sections[0][0])
+  end
+end

data/test/test_skippable_lines.rb

@@ -0,0 +1,64 @@
+require File.expand_path('../helper', __FILE__)
+
+class RoccoSkippableLines < Test::Unit::TestCase
+  def test_shebang_first_line
+    r = Rocco.new( 'filename.sh' ) { "" }
+    assert_equal(
+      [
+        [ [ "Comment 1" ], [ "def codeblock" ] ],
+        [ [ "Comment 2" ], [ "end" ] ]
+      ],
+      r.parse( "#!/usr/bin/env bash\n# Comment 1\ndef codeblock\n# Comment 2\nend\n" ),
+      "Shebang should be stripped when it appears as the first line."
+    )
+  end
+
+  def test_shebang_in_content
+    r = Rocco.new( 'filename.sh' ) { "" }
+    assert_equal(
+      [
+        # @TODO: `#!/` shouldn't be recognized as a comment.
+        [ [ "Comment 1", "!/usr/bin/env bash" ], [ "def codeblock" ] ],
+        [ [ "Comment 2" ], [ "end" ] ]
+      ],
+      r.parse( "# Comment 1\n#!/usr/bin/env bash\ndef codeblock\n# Comment 2\nend\n" ),
+      "Shebang shouldn't be stripped anywhere other than as the first line."
+    )
+  end
+
+  def test_encoding_in_ruby
+    r = Rocco.new( 'filename.rb' ) { "" }
+    assert_equal(
+      [
+        [ [ "Comment 1" ], [ "def codeblock" ] ],
+        [ [ "Comment 2" ], [ "end" ] ]
+      ],
+      r.parse( "#!/usr/bin/env bash\n# encoding: utf-8\n# Comment 1\ndef codeblock\n# Comment 2\nend\n" ),
+      "Strings matching the PEP 263 encoding definition regex should be stripped when they appear at the top of a python document."
+    )
+  end
+
+  def test_encoding_in_python
+    r = Rocco.new( 'filename.py' ) { "" }
+    assert_equal(
+      [
+        [ [ "Comment 1" ], [ "def codeblock" ] ],
+        [ [ "Comment 2" ], [ "end" ] ]
+      ],
+      r.parse( "#!/usr/bin/env bash\n# encoding: utf-8\n# Comment 1\ndef codeblock\n# Comment 2\nend\n" ),
+      "Strings matching the PEP 263 encoding definition regex should be stripped when they appear at the top of a python document."
+    )
+  end
+
+  def test_encoding_in_notpython
+    r = Rocco.new( 'filename.sh' ) { "" }
+    assert_equal(
+      [
+        [ [ "encoding: utf-8", "Comment 1" ], [ "def codeblock" ] ],
+        [ [ "Comment 2" ], [ "end" ] ]
+      ],
+      r.parse( "#!/usr/bin/env bash\n# encoding: utf-8\n# Comment 1\ndef codeblock\n# Comment 2\nend\n" ),
+      "Strings matching the PEP 263 encoding definition regex should be stripped when they appear at the top of a python document."
+    )
+  end
+end

data/test/test_source_list.rb

@@ -0,0 +1,29 @@
+require File.expand_path('../helper', __FILE__)
+
+class RoccoSourceListTests < Test::Unit::TestCase
+  def test_flat_sourcelist
+    r = Rocco.new( 'issue26.sh', [ 'issue26a.sh', 'issue26b.sh', 'issue26c.sh' ] ) {
+        "# Comment 1\n# Comment 1\nprint 'omg!'"
+    }
+    html = r.to_html
+    assert(
+      html.include?( '<a class="source" href="issue26a.html">issue26a.sh</a>' ) &&
+      html.include?( '<a class="source" href="issue26b.html">issue26b.sh</a>' ) &&
+      html.include?( '<a class="source" href="issue26c.html">issue26c.sh</a>' ),
+      "URLs correctly generated for files in a flat directory structure"
+    )
+  end
+
+  def test_heiarachical_sourcelist
+    r = Rocco.new( 'a/issue26.sh', [ 'a/issue26a.sh', 'b/issue26b.sh', 'c/issue26c.sh' ] ) {
+        "# Comment 1\n# Comment 1\nprint 'omg!'"
+    }
+    html = r.to_html
+    assert(
+      html.include?( '<a class="source" href="issue26a.html">issue26a.sh</a>' ) &&
+      html.include?( '<a class="source" href="../b/issue26b.html">issue26b.sh</a>' ) &&
+      html.include?( '<a class="source" href="../c/issue26c.html">issue26c.sh</a>' ),
+      "URLs correctly generated for files in a flat directory structure"
+    )
+  end
+end

metadata

@@ -1,19 +1,21 @@
 --- !ruby/object:Gem::Specification 
 name: rocco
 version: !ruby/object:Gem::Version 
+  hash: 7
   prerelease: false
   segments: 
   - 0
-  - 5
-  version: "0.5"
+  - 6
+  version: "0.6"
 platform: ruby
 authors: 
 - Ryan Tomayko
+- Mike West
 autorequire: 
 bindir: bin
 cert_chain: []
 
-date: 2010-09-10 00:00:00 -07:00
+date: 2011-03-05 00:00:00 -08:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -24,6 +26,7 @@ dependencies:
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
+        hash: 3
         segments: 
         - 0
         version: "0"
@@ -37,13 +40,16 @@ dependencies:
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
+        hash: 3
         segments: 
         - 0
         version: "0"
   type: :runtime
   version_requirements: *id002
 description: Docco in Ruby
-email: r@tomayko.com
+email: 
+- r@tomayko.com
+- <mike@mikewest.org>
 executables: 
 - rocco
 extensions: []
@@ -51,6 +57,7 @@ extensions: []
 extra_rdoc_files: []
 
 files: 
+- CHANGES.md
 - COPYING
 - README
 - Rakefile
@@ -60,6 +67,19 @@ files:
 - lib/rocco/layout.rb
 - lib/rocco/tasks.rb
 - rocco.gemspec
+- test/fixtures/issue10.iso-8859-1.rb
+- test/fixtures/issue10.utf-8.rb
+- test/helper.rb
+- test/suite.rb
+- test/test_basics.rb
+- test/test_block_comments.rb
+- test/test_comment_normalization.rb
+- test/test_commentchar_detection.rb
+- test/test_descriptive_section_names.rb
+- test/test_language_detection.rb
+- test/test_reported_issues.rb
+- test/test_skippable_lines.rb
+- test/test_source_list.rb
 has_rdoc: true
 homepage: http://rtomayko.github.com/rocco/
 licenses: []
@@ -74,6 +94,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
+      hash: 3
       segments: 
       - 0
       version: "0"
@@ -82,6 +103,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
+      hash: 3
       segments: 
       - 0
       version: "0"