rgabo-readability 0.1.0

data/lib/readability/readable.rb

@@ -0,0 +1,51 @@
+module Readability
+  module Readable
+    include Readability::Harmonizable
+
+    def read_style
+      @read_style ||= Readability::Style::NEWSPAPER
+    end
+    
+    def read_size
+      @read_size ||= Readability::Size::MEDIUM
+    end
+    
+    def read_margin
+      @read_margin ||= Readability::Margin::MEDIUM
+    end
+
+    attr_writer :read_style, :read_size, :read_margin
+    
+    def to_readable(args = {})
+      args[:content_only] ||= false
+      
+      # dup document
+      readable_doc = self.dup
+      
+      # remove all script tags
+      readable_doc.xpath('//script').each { |node| node.remove }
+      
+      readable_doc.harmony_page do |page|
+        # Set parameters
+        page.window.readStyle = @read_style
+        page.window.readSize = @read_size
+        page.window.readMargin = @read_margin
+        
+        # execute readability.js
+        page.load(File.join(File.dirname(__FILE__), 'js', 'readability.js'))
+      end
+      
+      # return <div id="readInner">...</div> if content_only
+      if args[:content_only]
+        return readable_doc.at_css("#readInner")
+      end
+      
+      # return document root
+      readable_doc.root
+    end
+    
+    def to_readable!(args = {})
+      self.root = to_readable(args)
+    end
+  end
+end

data/readability.gems

@@ -0,0 +1,30 @@
+# readability.gems generated gem export file. Note that any env variable settings will be missing. Append these after using a ';' field separator
+
+# nokogiri
+nokogiri -v1.4.1
+
+# harmony (johnson & envjs)
+stackdeck -v0.2.0
+johnson -v2.0.0.pre3
+envjs -v0.3.1
+harmony -v0.5.5
+
+# tomdoc
+hoe -v2.6.0
+ParseTree -v3.0.5
+RubyInline -v3.7.0
+ruby_parser -v2.0.4
+sexp_processor -v3.0.4
+colored -v1.2
+tomdoc -v0.1.0
+
+# jeweler
+gemcutter -v0.5.0
+git -v1.2.5
+json_pure -v1.4.3
+rubyforge -v2.0.4
+jeweler -v1.4.0
+
+# rspec
+rspec -v1.3.0
+syntax -v1.0.0

data/rgabo-readability.gemspec

@@ -0,0 +1,72 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run the gemspec command
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{rgabo-readability}
+  s.version = "0.1.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Gabor Ratky"]
+  s.date = %q{2010-05-16}
+  s.description = %q{Extends Nokogiri::HTML::Document to run Arc90's Readability and procude easy to read HTML documents.}
+  s.email = %q{rgabo@rgabostyle.com}
+  s.extra_rdoc_files = [
+    "LICENSE",
+     "README.rdoc"
+  ]
+  s.files = [
+    ".document",
+     ".gitignore",
+     "LICENSE",
+     "README.rdoc",
+     "Rakefile",
+     "VERSION",
+     "example.rb",
+     "lib/readability.rb",
+     "lib/readability/harmonizable.rb",
+     "lib/readability/js/readability.js",
+     "lib/readability/readable.rb",
+     "readability.gems",
+     "rgabo-readability.gemspec",
+     "spec/files/change_title.js",
+     "spec/files/tomdoc-reasonable-ruby-documentation.html",
+     "spec/readability/harmonizable_spec.rb",
+     "spec/readability/readable_spec.rb",
+     "spec/readability_spec.rb",
+     "spec/spec.opts",
+     "spec/spec_helper.rb"
+  ]
+  s.homepage = %q{http://github.com/rgabo/readability}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.7}
+  s.summary = %q{Run Arc90's Readability on Nokogiri documents}
+  s.test_files = [
+    "spec/readability/harmonizable_spec.rb",
+     "spec/readability/readable_spec.rb",
+     "spec/readability_spec.rb",
+     "spec/spec_helper.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_development_dependency(%q<rspec>, [">= 1.3.0"])
+      s.add_runtime_dependency(%q<harmony>, ["= 0.5.5"])
+      s.add_runtime_dependency(%q<nokogiri>, ["~> 1.4"])
+    else
+      s.add_dependency(%q<rspec>, [">= 1.3.0"])
+      s.add_dependency(%q<harmony>, ["= 0.5.5"])
+      s.add_dependency(%q<nokogiri>, ["~> 1.4"])
+    end
+  else
+    s.add_dependency(%q<rspec>, [">= 1.3.0"])
+    s.add_dependency(%q<harmony>, ["= 0.5.5"])
+    s.add_dependency(%q<nokogiri>, ["~> 1.4"])
+  end
+end
+

data/spec/files/change_title.js

@@ -0,0 +1 @@
+document.title = "Oops, I did it again."

data/spec/files/tomdoc-reasonable-ruby-documentation.html

@@ -0,0 +1,123 @@
+<!DOCTYPE html>
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en-us">
+<head>
+   <meta http-equiv="content-type" content="text/html; charset=utf-8" />
+   <title>TomDoc - Reasonable Ruby Documentation</title>
+   <meta name="author" content="Tom Preston-Werner" />
+   <link href="http://feeds.feedburner.com/tom-preston-werner" rel="alternate" title="Tom Preston-Werner" type="application/atom+xml" />
+
+   <!-- syntax highlighting CSS -->
+   <link rel="stylesheet" href="/css/syntax.css" type="text/css" />
+
+   <!-- Homepage CSS -->
+   <link rel="stylesheet" href="/css/screen.css" type="text/css" media="screen, projection" />
+
+   <!-- Typekit -->
+   <script type="text/javascript" src="http://use.typekit.com/jpd0pfm.js"></script>
+   <script type="text/javascript">try{Typekit.load();}catch(e){}</script>
+</head>
+<body>
+
+<!-- ClickTale Top part -->
+<script type="text/javascript">
+var WRInitTime=(new Date()).getTime();
+</script>
+<!-- ClickTale end of Top part -->
+
+<div class="site">
+  <div class="title">
+    <a href="/">Tom Preston-Werner</a>
+    <a class="extra" href="/">home</a>
+  </div>
+  
+  <div id="post">
+<h1>TomDoc &#8211; Reasonable Ruby Documentation</h1>
+<p class="meta">11 May 2010 &#8211; San Francisco</p>
+<p><a href="http://rdoc.rubyforge.org">RDoc</a> is an abomination. It&#8217;s ugly to read in plain text, requires the use of the inane :nodoc: tag to prevent private method documentation from showing up in final rendering, and does nothing to encourage complete or unambiguous documentation of classes, methods, or parameters. <a href="http://yardoc.org"><span class="caps">YARD</span></a> is much better but goes too far in the other direction (and still doesn&#8217;t look good in plain text). Providing an explicit way to specify parameters and types is great, but having to remember a bunch of strict tag names in order to be compliant is not a good way to encourage coders to write documentation. And again we see a @private tag that&#8217;s necessary to hide docs from the final render.</p>
+<p>Three years ago, after suffering with these existing documentation formats for far too long, I started using my own documentation format. It looked a bit like RDoc but had a set of conventions for specifying parameters, return values, and the expected types. It used plain language and full sentences so that a human could read and understand it without having to parse machine-oriented tags or crufty markup. I called this format TomDoc, because if Linus can name stuff after himself, then why can&#8217;t I?</p>
+<p>After years in the making, TomDoc is finally a well specified documentation format. You can find the full spec at <a href="http://tomdoc.org">http://tomdoc.org</a>.</p>
+<p>But enough talk. Here&#8217;s a sample of what a TomDoc&#8217;d method might look like:</p>
+<div class="highlight"><pre><code class="ruby"><span class="c1"># Public: Duplicate some text an abitrary number of times.</span>
+<span class="c1">#</span>
+<span class="c1"># text  - The String to be duplicated.</span>
+<span class="c1"># count - The Integer number of times to duplicate the text.</span>
+<span class="c1">#</span>
+<span class="c1"># Examples</span>
+<span class="c1">#</span>
+<span class="c1">#   multiplex(&#39;Tom&#39;, 4)</span>
+<span class="c1">#   # =&gt; &#39;TomTomTomTom&#39;</span>
+<span class="c1">#</span>
+<span class="c1"># Returns the duplicated String.</span>
+<span class="k">def</span> <span class="nf">multiplex</span><span class="p">(</span><span class="n">text</span><span class="p">,</span> <span class="n">count</span><span class="p">)</span>
+  <span class="n">text</span> <span class="o">*</span> <span class="n">count</span>
+<span class="k">end</span>
+</code></pre>
+</div><p>At first glance you&#8217;ll notice a few things. First, and most important, is that the documentation looks nice in plain text. When I&#8217;m working on a project, I need to be able to scan and read method documentation quickly. Littering the docs with tags and markup (especially <span class="caps">HTML</span> markup) is not acceptable. Code documentation should be optimized for human consumption. Second, all parameters and return values, and their expected types are specified. Types are generally denoted by class name. Because Ruby is so flexible, you are not constrained by a rigid type declaration syntax and are free to explain precisely how the expected types may vary under different circumstances. Finally, the basic layout is designed to be easy to remember. Once you commit a few simple conventions to memory, writing documentation becomes second nature, with all of the tricky decision making already done for you.</p>
+<p>Today&#8217;s Ruby libraries suffer deeply from haphazard versioning schemes. Even RubyGems itself does not follow a sane or predictable versioning pattern. This lack of discipline stems from the absence of well defined Public APIs. TomDoc attempts to solve this problem by making it simple to define an unambiguous Public <span class="caps">API</span> for your library. Instead of assuming that all classes and methods are intended for public consumption, TomDoc makes the Public <span class="caps">API</span> opt-in. To denote that something is public, all you have to do is preface the main description with &#8220;Public:&#8221;. By forcing you to explicitly state that a class or method is intended for public consumption, a deliberate and thoughtful Public <span class="caps">API</span> is automatically constructed that can inform disciplined version changes according to the tenets of <a href="http://semver.org">Semantic Versioning</a>. In addition, the prominent display of &#8220;Public&#8221; in a method description ensures that developers are made aware of the sensitive nature of the method and do not carelessly change the signature of something in the Public <span class="caps">API</span>.</p>
+<p>Once a Public <span class="caps">API</span> has been established, some very exciting things become possible. We&#8217;re currently working on a processing tool that will render TomDoc into various forms (terminal, <span class="caps">HTML</span>, etc). If you run this tool on a library, you&#8217;ll get a printout of the Public <span class="caps">API</span> documentation. You can publish this online so that others have easy access to it. When you roll a new version of the library, you can run the tool again, giving it a prior version as a base, and have it automatically display only the methods that have changed. This diff will be extremely useful for users while they upgrade to the new version (or so they can evaluate whether an upgrade is warrented)!</p>
+<p>While I&#8217;ve been using various nascent forms of TomDoc for several years, we&#8217;re just now starting to adopt it for everything we do at GitHub. Now that I&#8217;ve formalized the spec it will be easy for the entire team to write compliant TomDoc. The goal is to have every class, method, and accessor of every GitHub library documented. In the future, once we have proper tooling, we&#8217;d even like to create a unit test that will fail if anything is missing documentation.</p>
+<p>TomDoc is still a rough specification so I&#8217;m initially releasing it as 0.9.0. Over the coming months I&#8217;ll make any necessary changes to address user concerns and release a 1.0.0 version once things have stabilized. If you&#8217;d like to suggest changes, please open an issue on the <a href="http://github.com/mojombo/tomdoc">TomDoc GitHub repository</a>.</p>
+</div>
+
+<div id="related">
+  <h2>Related Posts</h2>
+  <ul class="posts">
+    
+      <li><span>19 May 2009</span> &raquo; <a href="/2009/05/19/the-git-parable.html">The Git Parable</a></li>
+    
+      <li><span>17 Nov 2008</span> &raquo; <a href="/2008/11/17/blogging-like-a-hacker.html">Blogging Like a Hacker</a></li>
+    
+      <li><span>03 Nov 2008</span> &raquo; <a href="/2008/11/03/how-to-meet-your-next-cofounder.html">How to Meet Your Next Cofounder</a></li>
+    
+  </ul>
+</div>
+  
+  <div class="footer">
+    <div class="contact">
+      <p>
+        Tom Preston-Werner<br />
+        Cofounder of <a href="http://github.com/">GitHub</a><br />
+        tom@mojombo.com
+      </p>
+    </div>
+    <div class="contact">
+      <p>
+        <a href="http://github.com/mojombo/">github.com/mojombo</a><br />
+        <a href="http://twitter.com/mojombo/">twitter.com/mojombo</a><br />
+        <a href="http://flickr.com/photos/mojombo/">flickr.com/photos/mojombo</a>
+      </p>
+    </div>
+    <div class="rss">
+      <a href="http://feeds.feedburner.com/tom-preston-werner">
+        <img src="/images/rss.png" alt="Subscribe to RSS Feed" />
+      </a>
+    </div>
+  </div>
+</div>
+
+<a href="http://github.com/mojombo"><img style="position: absolute; top: 0; right: 0; border: 0;" src="http://s3.amazonaws.com/github/ribbons/forkme_right_red_aa0000.png" alt="Fork me on GitHub" /></a>
+
+<!-- ClickTale Bottom part -->
+<div id="ClickTaleDiv" style="display: none;"></div>
+<script type="text/javascript">
+if(document.location.protocol!='https:')
+  document.write(unescape("%3Cscript%20src='http://s.clicktale.net/WRb.js'%20type='text/javascript'%3E%3C/script%3E"));
+</script>
+<script type="text/javascript">
+if(typeof ClickTale=='function') ClickTale(206,0.3,"www03");
+</script>
+<!-- ClickTale end of Bottom part -->
+
+<!-- Google Analytics -->
+<script type="text/javascript">
+var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www.");
+document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E"));
+</script>
+<script type="text/javascript">
+var pageTracker = _gat._getTracker("UA-6016902-1");
+pageTracker._trackPageview();
+</script>
+<!-- Google Analytics end -->
+
+</body>
+</html>

data/spec/readability/harmonizable_spec.rb

@@ -0,0 +1,36 @@
+require File.expand_path(File.dirname(__FILE__) + '/../spec_helper')
+require 'open-uri'
+
+describe Readability::Harmonizable do
+  before :each do
+    @doc = Nokogiri::HTML(open(File.dirname(__FILE__) + '/../files/tomdoc-reasonable-ruby-documentation.html'))
+  end
+    
+  it "extends Nokogiri::HTML::Document" do
+    Nokogiri::HTML::Document.include?(Readability::Harmonizable).should be_true
+  end
+
+  it "allows access to the DOM" do
+    @doc.window.should_not be_nil
+    @doc.window.document.should_not be_nil
+  end
+  
+  it "allows changes to the DOM" do
+    @doc.window do |window|
+      window.document.title = "foobar"
+    end
+    
+    @doc.window.document.title.should == "foobar"
+  end
+
+  it "executes javascript code on the document" do
+    # check original title
+    @doc.window.document.title.should == "TomDoc - Reasonable Ruby Documentation"
+    
+    # set new title
+    @doc.execute_js("document.title = 'foobar'")
+    
+    # document.title should have new title
+    @doc.window.document.title.should == "foobar"
+  end
+end

data/spec/readability/readable_spec.rb

@@ -0,0 +1,50 @@
+require File.expand_path(File.dirname(__FILE__) + '/../spec_helper')
+
+describe Readability::Readable do
+  before :each do
+    @doc = Nokogiri::HTML(open(File.dirname(__FILE__) + '/../files/tomdoc-reasonable-ruby-documentation.html'))
+  end
+    
+  it "extends Nokogiri::HTML::Document" do
+    Nokogiri::HTML::Document.include?(Readability::Readable).should be_true
+  end
+  
+  it "can set Readability variables" do
+    @doc.read_style = Readability::Style::NEWSPAPER
+    @doc.read_size = Readability::Size::MEDIUM
+    @doc.read_margin = Readability::Margin::MEDIUM
+    
+    @doc.read_style.should == Readability::Style::NEWSPAPER
+    @doc.read_size.should == Readability::Size::MEDIUM
+    @doc.read_margin.should == Readability::Margin::MEDIUM
+  end
+  
+  it "can run Readability and return resulting document" do
+    # original document includes link to flickr
+    @doc.to_html.should include "flickr.com/photos/mojombo"
+    
+    readable_doc = @doc.to_readable
+
+    # readable version should not include the link to flickr
+    readable_doc.should_not be_nil
+    readable_doc.to_html.should_not include "flickr.com/photos/mojombo"
+  end
+  
+  it "can run Readability in place" do
+    # original document includes link to flickr
+    @doc.to_html.should include "flickr.com/photos/mojombo"
+    
+    @doc.to_readable!
+    
+    # readable version should not include the link to flickr
+    @doc.to_html.should_not include "flickr.com/photos/mojombo"
+  end
+  
+  it "can return the content only" do
+    content = @doc.to_readable(:content_only => false)
+    content.to_html.should include "Original Page"
+    
+    content = @doc.to_readable(:content_only => true)
+    content.to_html.should_not include "Original Page"
+  end
+end

data/spec/readability_spec.rb

@@ -0,0 +1,4 @@
+require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
+
+describe Readability do
+end

data/spec/spec.opts

@@ -0,0 +1 @@
+--color

data/spec/spec_helper.rb

@@ -0,0 +1,9 @@
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+require 'readability'
+require 'spec'
+require 'spec/autorun'
+
+Spec::Runner.configure do |config|
+  
+end

metadata

@@ -0,0 +1,136 @@
+--- !ruby/object:Gem::Specification 
+name: rgabo-readability
+version: !ruby/object:Gem::Version 
+  hash: 27
+  prerelease: false
+  segments: 
+  - 0
+  - 1
+  - 0
+  version: 0.1.0
+platform: ruby
+authors: 
+- Gabor Ratky
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-05-16 00:00:00 +02:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 27
+        segments: 
+        - 1
+        - 3
+        - 0
+        version: 1.3.0
+  type: :development
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: harmony
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - "="
+      - !ruby/object:Gem::Version 
+        hash: 1
+        segments: 
+        - 0
+        - 5
+        - 5
+        version: 0.5.5
+  type: :runtime
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: nokogiri
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 7
+        segments: 
+        - 1
+        - 4
+        version: "1.4"
+  type: :runtime
+  version_requirements: *id003
+description: Extends Nokogiri::HTML::Document to run Arc90's Readability and procude easy to read HTML documents.
+email: rgabo@rgabostyle.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE
+- README.rdoc
+files: 
+- .document
+- .gitignore
+- LICENSE
+- README.rdoc
+- Rakefile
+- VERSION
+- example.rb
+- lib/readability.rb
+- lib/readability/harmonizable.rb
+- lib/readability/js/readability.js
+- lib/readability/readable.rb
+- readability.gems
+- rgabo-readability.gemspec
+- spec/files/change_title.js
+- spec/files/tomdoc-reasonable-ruby-documentation.html
+- spec/readability/harmonizable_spec.rb
+- spec/readability/readable_spec.rb
+- spec/readability_spec.rb
+- spec/spec.opts
+- spec/spec_helper.rb
+has_rdoc: true
+homepage: http://github.com/rgabo/readability
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: Run Arc90's Readability on Nokogiri documents
+test_files: 
+- spec/readability/harmonizable_spec.rb
+- spec/readability/readable_spec.rb
+- spec/readability_spec.rb
+- spec/spec_helper.rb