RubyGems - fl-rocco - Versions diffs - 1.0.0 - Mend

fl-rocco 1.0.0

Files changed (30) hide show

data/CHANGES.md +73 -0
data/COPYING +18 -0
data/README +23 -0
data/Rakefile +115 -0
data/bin/rocco +74 -0
data/lib/rocco.rb +493 -0
data/lib/rocco/comment_styles.rb +56 -0
data/lib/rocco/layout.mustache +46 -0
data/lib/rocco/layout.rb +64 -0
data/lib/rocco/tasks.rb +123 -0
data/lib/rocco/version.rb +3 -0
data/rocco.gemspec +65 -0
data/test/fixtures/issue10.iso-8859-1.rb +1 -0
data/test/fixtures/issue10.utf-8.rb +1 -0
data/test/helper.rb +25 -0
data/test/suite.rb +5 -0
data/test/test_basics.rb +63 -0
data/test/test_block_comment_styles.rb +64 -0
data/test/test_block_comments.rb +101 -0
data/test/test_comment_normalization.rb +25 -0
data/test/test_commentchar_detection.rb +28 -0
data/test/test_descriptive_section_names.rb +30 -0
data/test/test_docblock_annotations.rb +23 -0
data/test/test_heredoc.rb +13 -0
data/test/test_language_detection.rb +27 -0
data/test/test_reported_issues.rb +84 -0
data/test/test_skippable_lines.rb +64 -0
data/test/test_source_list.rb +29 -0
data/test/test_stylesheet.rb +23 -0
metadata +110 -0

@@ -0,0 +1,56 @@
+class Rocco
+  module CommentStyles
+    C_STYLE_COMMENTS = {
+      :single => "//",
+      :multi  => { :start => "/**", :middle => "*", :end => "*/" },
+      :heredoc => nil
+    }
+    COMMENT_STYLES  = {
+      "bash"          =>  { :single => "#", :multi => nil },
+      "c"             =>  C_STYLE_COMMENTS,
+      "coffee-script" =>  {
+        :single => "#",
+        :multi  => { :start => "###", :middle => nil, :end => "###" },
+        :heredoc => nil
+      },
+      "cpp" =>  C_STYLE_COMMENTS,
+      "csharp" => C_STYLE_COMMENTS,
+      "css"           =>  {
+        :single => nil,
+        :multi  => { :start => "/**", :middle => "*", :end => "*/" },
+        :heredoc => nil
+      },
+      "html"           =>  {
+        :single => nil,
+        :multi => { :start => '<!--', :middle => nil, :end => '-->' },
+        :heredoc => nil
+      },
+      "java"          =>  C_STYLE_COMMENTS,
+      "js"            =>  C_STYLE_COMMENTS,
+      "lua"           =>  {
+        :single => "--",
+        :multi => nil,
+        :heredoc => nil
+      },
+      "php" => C_STYLE_COMMENTS,
+      "python"        =>  {
+        :single => "#",
+        :multi  => { :start => '"""', :middle => nil, :end => '"""' },
+        :heredoc => nil
+      },
+      "rb"            =>  {
+        :single => "#",
+        :multi  => { :start => '=begin', :middle => nil, :end => '=end' },
+        :heredoc => "<<-"
+      },
+      "scala"         =>  C_STYLE_COMMENTS,
+      "scheme"        =>  { :single => ";;",  :multi => nil, :heredoc => nil },
+      "xml"           =>  {
+        :single => nil,
+        :multi => { :start => '<!--', :middle => nil, :end => '-->' },
+        :heredoc => nil
+      },
+    }
+  end
+end

data/lib/rocco/layout.mustache ADDED

@@ -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="{{ stylesheet }}">
+</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-{{ section_id }}'>
+      <td class=docs>
+        <div class="pilwrap">
+          <a class="pilcrow" href="#section-{{ section_id }}">&#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 ADDED

@@ -0,0 +1,64 @@
+require 'mustache'
+require 'pathname'
+class Rocco::Layout < Mustache
+  self.template_path = "#{File.dirname(__FILE__)}/.."
+  def initialize(doc, stylesheet, file=nil)
+    @doc = doc
+    @stylesheet = stylesheet
+    if not file.nil?
+      Rocco::Layout.template_file = file
+    end
+  end
+  def title
+    File.basename(@doc.file)
+  end
+  def stylesheet
+    @stylesheet
+  end
+  def file
+    @doc.file
+  end
+  def sections
+    num = 0
+    @doc.sections.map do |docs,code|
+      code ||= ''
+      is_header = /^<h.>(.+)<\/h.>$/.match( docs )
+      header_text = is_header && is_header[1].split.join("_")
+      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
+  def sources?
+    @doc.sources.length > 1
+  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        => htmlpath.relative_path_from( currentpath )
+      }
+    end
+  end
+end

data/lib/rocco/tasks.rb ADDED

@@ -0,0 +1,123 @@
+#### 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
+    include Rake::DSL if defined?(Rake::DSL)
+    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 = 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.
+        # 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)
+        FileUtils.mkdir_p(File.dirname(dest_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/lib/rocco/version.rb ADDED

@@ -0,0 +1,3 @@
+class Rocco
+  VERSION = '1.0.0'
+end

data/rocco.gemspec ADDED

@@ -0,0 +1,65 @@
+# rocco.gemspec
+#
+# To update this file's version, date, and file list, change the VERSION
+# constant in lib/rocco.rb and run `rake rocco.gemspec`.
+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 = 'fl-rocco'
+  s.version = '1.0.0'
+  s.date = '2012-01-10'
+  s.description = "Docco in Ruby"
+  s.summary     = s.description
+  s.authors = ["Ryan Tomayko", "Mike West"]
+  s.email   = ["r@tomayko.com", "<mike@mikewest.org>"]
+  # = MANIFEST =
+  s.files = %w[
+    CHANGES.md
+    COPYING
+    README
+    Rakefile
+    bin/rocco
+    lib/rocco.rb
+    lib/rocco/comment_styles.rb
+    lib/rocco/layout.mustache
+    lib/rocco/layout.rb
+    lib/rocco/tasks.rb
+    lib/rocco/version.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_comment_styles.rb
+    test/test_block_comments.rb
+    test/test_comment_normalization.rb
+    test/test_commentchar_detection.rb
+    test/test_descriptive_section_names.rb
+    test/test_docblock_annotations.rb
+    test/test_heredoc.rb
+    test/test_language_detection.rb
+    test/test_reported_issues.rb
+    test/test_skippable_lines.rb
+    test/test_source_list.rb
+    test/test_stylesheet.rb
+  ]
+  # = MANIFEST =
+  s.executables = ["rocco"]
+  s.test_files = s.files.select {|path| path =~ /^test\/.*_test.rb/}
+  s.add_dependency 'redcarpet', '~> 1.17'
+  s.add_dependency 'mustache'
+  s.add_development_dependency 'rake', '~> 0.9'
+  s.has_rdoc = false
+  s.homepage = "http://rtomayko.github.com/rocco/"
+  s.require_paths = %w[lib]
+  s.rubygems_version = '1.1.1'
+end

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

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

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

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

data/test/helper.rb ADDED

@@ -0,0 +1,25 @@
+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
+def fb_assert_val( str )
+  return str.strip if Rocco::MD_BLUECLOTH
+  str
+end

data/test/suite.rb ADDED

@@ -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 ADDED

@@ -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 fb_assert_val("<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