RubyGems - rgabo-readability - Versions diffs - 0.1.1 → 0.1.2 - Mend

rgabo-readability 0.1.1 → 0.1.2

Files changed (11) hide show

data/.rvmrc +1 -0
data/VERSION +1 -1
data/lib/readability/readable.rb +9 -2
data/rgabo-readability.gemspec +7 -2
data/spec/files/script.js +1 -0
data/spec/files/techcrunch-article.html +983 -0
data/spec/files/tomdoc-script_test.html +112 -0
data/spec/readability/harmonizable_spec.rb +1 -0
data/spec/readability/readable_spec.rb +47 -0
data/spec/readability/urls.yaml +8 -0
metadata +9 -4

data/spec/files/tomdoc-script_test.html ADDED Viewed

@@ -0,0 +1,112 @@
+<!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" />
+   <script type="text/javascript" src="script.js"></script>
+   <script type="text/javascript">document.title = "failed";</script>
+</head>
+<body>
+<script type="text/javascript">
+  document.title = "failed";
+</script>
+<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>
+<div id="ClickTaleDiv" style="display: none;"></div>
+<script type="text/javascript">
+document.write(unescape("%3Cscript%20src='script.js'%20type='text/javascript'%3E%3C/script%3E"));
+</script>
+<script type="text/javascript">
+document.write(unescape("%3Cscript%20type='text/javascript'%3E%20document.title = 'failed'%20%3C/script%3E"));
+</script>
+<script type="text/javascript">
+document.title = "failed"
+</script>
+</body>
+</html>

data/spec/readability/harmonizable_spec.rb CHANGED Viewed

@@ -4,6 +4,7 @@ require 'open-uri'
 describe Readability::Harmonizable do
   before :each do
     @doc = Nokogiri::HTML(open(File.dirname(__FILE__) + '/../files/tomdoc-reasonable-ruby-documentation.html'))
+    @doc.remove('script')
   end
   it "extends Nokogiri::HTML::Document" do

data/spec/readability/readable_spec.rb CHANGED Viewed

@@ -1,5 +1,8 @@
 require File.expand_path(File.dirname(__FILE__) + '/../spec_helper')
+require 'open-uri'
+require 'yaml'
 describe Readability::Readable do
   before :each do
     @doc = Nokogiri::HTML(open(File.dirname(__FILE__) + '/../files/tomdoc-reasonable-ruby-documentation.html'))
@@ -48,3 +51,47 @@ describe Readability::Readable do
     content.to_html.should_not include "Original Page"
   end
 end
+describe "Readability.js" do
+  class << self
+    def test_with(url)
+      self.class_eval do <<-EOF
+        def it "should work on #{url}" do
+          # load webpage
+          @doc = Nokogiri::HTML(open("#{url}"))
+          # run readability in place
+          @doc.to_readable!
+          @doc.to_html.should include('Readability version 1.5.0')
+        end
+  EOF
+      end
+    end
+  end
+  it "should not execute any Javascript" do
+    # load modified version of the tomdoc post
+    @doc = Nokogiri::HTML(open(File.dirname(__FILE__) + '/../files/tomdoc-script_test.html'))
+    # run readability in place
+    @doc.to_readable!
+    # check whether any script could change the title of the document
+    @doc.window.document.title.should_not == "failed"
+  end
+  it "should not fail on any article" do
+    urls = YAML.load(File.open(File.join(File.dirname(__FILE__), 'urls.yaml')))
+    urls.each do |url|
+      # load webpage
+      @doc = Nokogiri::HTML(open(url))
+      # run readability in place
+      @doc.to_readable!
+      @doc.to_html.should include('Readability version 1.5.0')
+    end
+  end
+end

data/spec/readability/urls.yaml ADDED Viewed

@@ -0,0 +1,8 @@
+# Array of URLs to test readability with
+ - 'http://techcrunch.com/2010/05/16/groupon-invades-europe-with-acquisition-of-citydeal'
+ - 'http://blogs.wsj.com/venturecapital/2010/05/14/despite-short-term-improvement-vc-10-year-index-goes-negative/?mod=rss_WSJBlog'
+ - 'http://www.engadget.com/2010/04/03/entelligence-the-ipad-as-a-productivity-tool/'
+# - 'http://www.huffingtonpost.com/2010/05/15/delete-facebook-account-q_n_576956.html'
+ - 'http://mashable.com/2010/05/16/in-defense-of-facebook/'
+ - 'http://feeds.venturebeat.com/~r/Venturebeat/~3/rYPVBROMiEI/'
+ - 'http://eu.techcrunch.com/2010/04/25/new-eu-rules-could-kill-off-european-vc-and-screw-startups-lets-stop-them/'

metadata CHANGED Viewed

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: rgabo-readability
 version: !ruby/object:Gem::Version
-  hash: 25
+  hash: 31
   prerelease: false
   segments:
   - 0
   - 1
-  - 1
-  version: 0.1.1
+  - 2
+  version: 0.1.2
 platform: ruby
 authors:
 - Gabor Ratky
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
-date: 2010-05-16 00:00:00 +02:00
+date: 2010-05-17 00:00:00 +02:00
 default_executable:
 dependencies:
 - !ruby/object:Gem::Dependency
@@ -77,6 +77,7 @@ extra_rdoc_files:
 files:
 - .document
 - .gitignore
+- .rvmrc
 - LICENSE
 - README.rdoc
 - Rakefile
@@ -89,9 +90,13 @@ files:
 - readability.gems
 - rgabo-readability.gemspec
 - spec/files/change_title.js
+- spec/files/script.js
+- spec/files/techcrunch-article.html
 - spec/files/tomdoc-reasonable-ruby-documentation.html
+- spec/files/tomdoc-script_test.html
 - spec/readability/harmonizable_spec.rb
 - spec/readability/readable_spec.rb
+- spec/readability/urls.yaml
 - spec/readability_spec.rb
 - spec/spec.opts
 - spec/spec_helper.rb