Documentation revamp.

Signed-off-by: Aman Gupta <aman@tmm1.net>

.gitignore

@@ -14,3 +14,8 @@ Makefile
 *.dSYM
 java/src/.project
 *.rbc
+Gemfile.lock
+
+.yardoc/*
+doc/*
+

.yardopts

@@ -1,3 +1,7 @@
+--no-private
+--protected
+--markup="markdown" lib/**/*.rb
+--main README.md
 --exclude jeventmachine --exclude pure_ruby
 -
-docs/DEFERRABLES docs/EPOLL docs/KEYBOARD
+docs/*.md

Gemfile

@@ -1,2 +1,3 @@
 source :rubygems
 gemspec
+

README.md

@@ -0,0 +1,109 @@
+# About EventMachine #
+
+
+## What is EventMachine ##
+
+EventMachine is an event-driven I/O and lightweight concurrency library for Ruby.
+It provides event-driven I/O using the [Reactor pattern](http://en.wikipedia.org/wiki/Reactor_pattern),
+much like [JBoss Netty](http://www.jboss.org/netty), [Apache MINA](http://mina.apache.org/),
+Python's [Twisted](http://twistedmatrix.com), [Node.js](http://nodejs.org), libevent and libev.
+
+EventMachine is designed to simultaneously meet two key needs:
+
+ * Extremely high scalability, performance and stability for the most demanding production environments.
+ * An API that eliminates the complexities of high-performance threaded network programming,
+   allowing engineers to concentrate on their application logic.
+
+This unique combination makes EventMachine a premier choice for designers of critical networked
+applications, including Web servers and proxies, email and IM production systems, authentication/authorization
+processors, and many more.
+
+EventMachine has been around since yearly 2000s and is a mature and battle tested library.
+
+
+## What EventMachine is good for? ##
+
+ * Scalable event-driven servers. Examples: [Thin](http://code.macournoyer.com/thin/) or [Goliath](https://github.com/postrank-labs/goliath/).
+ * Scalable asynchronous clients for various protocols, RESTful APIs and so on. Examples: [em-http-request](https://github.com/igrigorik/em-http-request) or [amqp gem](https://github.com/ruby-amqp/amqp).
+ * Efficient network proxies with custom logic. Examples: [Proxymachine](https://github.com/mojombo/proxymachine/).
+ * File and network monitoring tools. Examples: [eventmachine-tail](https://github.com/jordansissel/eventmachine-tail) and [logstash](https://github.com/logstash/logstash).
+
+
+
+## What platforms are supported by EventMachine? ##
+
+EventMachine supports Ruby 1.8.7, 1.9.2, REE, JRuby and **works well on Windows** as well
+as many operating systems from the Unix family (Linux, Mac OS X, BSD flavors).
+
+
+
+## Install the gem ##
+
+Install it with [RubyGems](https://rubygems.org/)
+
+    gem install eventmachine
+
+or add this to your Gemfile if you use [Bundler](http://gembundler.com/):
+
+    gem "eventmachine"
+
+
+
+## Getting started ##
+
+For an introduction to EventMachine, check out:
+
+ * [blog post about EventMachine by Ilya Grigorik](http://www.igvita.com/2008/05/27/ruby-eventmachine-the-speed-demon/).
+ * [EventMachine Introductions by Dan Sinclair](http://everburning.com/news/eventmachine-introductions/).
+
+
+### Server example: Echo server ###
+
+Here's a fully-functional echo server written with EventMachine:
+
+     require 'eventmachine'
+
+     module EchoServer
+       def post_init
+         puts "-- someone connected to the echo server!"
+       end
+
+       def receive_data data
+         send_data ">>>you sent: #{data}"
+         close_connection if data =~ /quit/i
+       end
+
+       def unbind
+         puts "-- someone disconnected from the echo server!"
+      end
+    end
+
+    # Note that this will block current thread.
+    EventMachine.run {
+      EventMachine.start_server "127.0.0.1", 8081, EchoServer
+    }
+
+
+## EventMachine documentation ##
+
+Currently we only have [reference documentation](http://eventmachine.rubyforge.org) and a [wiki](https://github.com/eventmachine/eventmachine/wiki).
+
+
+## Community and where to get help ##
+
+ * Join the [mailing list](http://groups.google.com/group/eventmachine) (Google Group)
+ * Join IRC channel #eventmachine on irc.freenode.net
+
+
+## License and copyright ##
+
+EventMachine is copyrighted free software made available under the terms
+of either the GPL or Ruby's License.
+
+Copyright: (C) 2006-07 by Francis Cianfrocca. All Rights Reserved.
+
+
+## Alternatives ##
+
+If you are unhappy with EventMachine and want to use Ruby, check out [Cool.io](http://coolio.github.com/).
+One caveat: by May 2011, it did not support JRuby and Windows.

Rakefile

@@ -4,8 +4,16 @@ import  *Dir['tasks/*.rake']
 
 GEMSPEC = eval(File.read(File.expand_path('../eventmachine.gemspec', __FILE__)))
 
+require 'yard'
 require 'rake/clean'
 task :clobber => :clean
 
 desc "Build eventmachine, then run tests."
 task :default => [:compile, :test]
+
+desc 'Generate documentation'
+YARD::Rake::YardocTask.new do |t|
+  t.files   = ['lib/**/*.rb', '-', 'docs/*.md']
+  t.options = ['--main', 'README.md', '--no-private']
+  t.options = ['--exclude', 'lib/jeventmachine', '--exclude', 'lib/pr_eventmachine']
+end

docs/DocumentationGuidesIndex.md

@@ -0,0 +1,27 @@
+# EventMachine documentation guides #
+
+Welcome to the documentation guides for [EventMachine](http://github.com/eventmachine/eventmachine),
+a fast and simple event-processing library for Ruby programs (à la JBoss Netty, Twisted, Node.js
+and so on).
+
+## Guide list ##
+
+ * {file:docs/GettingStarted.md Getting started with EventMachine}
+ * {file:docs/EventDrivenServers.md Writing event-driven servers}
+ * {file:docs/EventDrivenClients.md Writing event-driven clients}
+ * {file:docs/ConnectionFailureAndRecovery.md Connection Failure and Recovery}
+ * {file:docs/TLS.md TLS (aka SSL)}
+ * {file:docs/Ecosystem.md EventMachine ecosystem}: Thin, Goliath, em-http-request, em-websockets, Proxymachine and beyond
+ * {file:docs/BlockingEventLoop.md On blocking the event loop: why it is harmful for performance and how to avoid it}
+ * {file:docs/LightweightConcurrency.md Lightweight concurrency with EventMachine}
+ * {file:docs/Deferrables.md Deferrables}
+ * {file:docs/ModernKernelInputOutputAPIs.md Brief introduction to epoll, kqueue, select}
+ * {file:docs/WorkingWithOtherIOSources.md Working with other IO sources such as the keyboard}
+
+
+## Tell us what you think! ##
+
+Please take a moment and tell us what you think about this guide on the [EventMachine mailing list](http://bit.ly/jW3cR3)
+or in the #eventmachine channel on irc.freenode.net: what was unclear? What wasn't covered?
+Maybe you don't like the guide style or the grammar and spelling are incorrect? Reader feedback is
+key to making documentation better.