Skip to content
This repository

Documentation revamp #212

Closed
wants to merge 79 commits into from

5 participants

Michael Klishin James Tucker Aman Gupta pete higgins dan sinclair
Michael Klishin

Documentation revamp I have been working on for a few weeks now is ready to be merged back. It is by no means as awesome as Postgres or Django documentation but now it has

  • N00b-friendly README written from scratch
  • A new lengthy tutorial
  • A skeleton for documentation guides
  • Rewritten/updated documentation for every key method out there
  • YARD @tags for method parameters, return values, options, etc.
  • Cross-references (again, thanks to YARD)

The diff is getting scary (6K lines or so already) so I decided maybe we should merge this first and then I can continue with other guides and API reference updates.

dan sinclair
dj2 commented on 87cf47f May 14, 2011

Why not just $: << "." << ".."

No particular reason. A habit of using Pathname, I guess.

Owner

Actually, I'd rather you just require 'eventmachine' and then use -I or fix the rake tasks.

Owner
tmm1 replied May 30, 2011

Please revert this. The 1.9 issues should be fixed in eventmachine/eventmachine@d326bb3

dan sinclair
dj2 commented on c71f564 May 16, 2011

If possible, can you wrap these to ~80 characters? I'd done this to all the docs initially as it makes viewing stuff on Github a lot nicer.

I will, however, links make it somewhat difficult. I wonder how relevant is this convention that emerged from tiny terminal screens in the 60s? :)

dj2 replied May 16, 2011

I don't really care if it's ~80. I just have a small laptop screen and when viewing on github at the current settings has horizontal scroll. So, the size I'm really looking for is, make your browser the smallest without horizontal page scroll and then make it fit, heh. I just know ~80chars does fit.

How wide is "small laptop screen"? I mostly work on a giant 27.5 inch Cinema Display and that's why I didn't find current formatting a problem. But sure, lets do it. Just tell me what width to target.

Ah, get the idea now. Target whatever page width github has w/o horizontal scrolling.

dj2 replied May 16, 2011

It's 15" laptop but I don't have my browser taking full screen. The browser is set at the minimum size possible without a horizontal scrollbar on the bottom. Basically, the minimum GitHub page width.

dan sinclair
dj2 commented on 0aae586 May 16, 2011

Perfect. Thanks.

dan sinclair
dj2 commented on c31d1ec May 17, 2011

Heh, I was wondering if you'd change that back.

and others added some commits May 18, 2011
Michael Klishin Move old examples to examples/old 1edf257
Michael Klishin Switch to YARD 0.7 that supports file includes: awesome for examples 7f40c54
Michael Klishin Add YARD 0.7.0 dependency in the .gemspec 926de43
Michael Klishin Initial bits of Getting Started guide, requires YARD 0.7+ e3d5128
dan sinclair add bluecloth to gemspec 8d26ae9
dan sinclair Defined in .gemspec, don't need in Gemfile 76ca7ff
dan sinclair restrict to .md docs 6f691ad
dan sinclair minor cleanups 8e0bdb8
Michael Klishin First example in the Getting Started guide is done 719e804
Michael Klishin Initial version of chat server example (in the Getting Started guide) d3a1fb9
Michael Klishin Add intermediate steps content for the Chat Server Example a78806d
Michael Klishin A typo 95413dc
Michael Klishin Improvements to the Getting Started Guide structure; Explain what it …
…doesn't demonstrate (intentionally)
4f9a975
Michael Klishin Wording, grammar 028684a
Michael Klishin Link to JRuby website f598ad5
Michael Klishin Add two more (not yet written) guides to the index 8b900a2
Michael Klishin Initial pass on porting the existing EventMachine::Connection documen…
…tation to YARD
fa09380
Michael Klishin Link to the (not yet written) TLS guide 1a4dfa6
Michael Klishin First shot at porting EventMachine (the module) documentation to YARD cac543a
Michael Klishin Improvements to EventMachine.run documentation
 * Explain what Unicorn, Passenger and Mongrel users should do if they want to
   run EventMachine event loop inside of their Web app.
f6978bd
Michael Klishin Update EventMachine.stop_event_loop documentation to explain where th…
…ose "connection termination callbacks" come from
a78404e
Michael Klishin Update EventMachine.connect documentation 0e747f6
Michael Klishin Update to EventMachine.start_server 77d597d
Michael Klishin Tiny update to EventMachine.add_timer documentation 8ca361a
Michael Klishin Tiny update to EventMachine.add_periodic_timer documentation b7ec259
Michael Klishin Rearrange EventMachine.defer documentation a bit 20eea13
Michael Klishin Update to EventMachine.enable_proxy documentation 6fad2a6
Michael Klishin Adhere to YARD's convention for #instance_methods and .class_methods 3b4de55
Michael Klishin Cosmetics a9ec292
Michael Klishin Update documentation for EventMachine.watch_file 320209a
Michael Klishin A typo 07461f6
Michael Klishin One more typo spotted by YARD 56fabaa
Michael Klishin Manually port dj2/eventmachine@707a0df 1036279
Michael Klishin Merge remote-tracking branch 'origin/master' into documentation_revamp d1390b9
Michael Klishin Another pass on EventMachine (the module, including methods) document…
…ation
6910df7
Michael Klishin Makes YARD actually pick up documentation on EventMachine::Connection cda8885
Michael Klishin Another pass on improvements to EventMachine::Connection documentation e39f482
Michael Klishin One more pass on EventMachine::Connection documentation 43a616b
Michael Klishin One more pass on EventMachine::Connection documentation 4b82c3b
Michael Klishin A typo e71c729
Michael Klishin More typos fa477ea
Michael Klishin

Interesting, GitHub says it's about 3K of diff. Anyway, it is pretty scary to diverge more and more since API reference updates affect a lot of files.

pete higgins phiggins commented on the diff May 25, 2011
docs/GettingStarted.md
((13 lines not shown))
  13
+
  14
+ * Installing EventMachine via [Rubygems](http://rubygems.org) and [Bundler](http://gembundler.com).
  15
+ * Building an Echo server, the "Hello, world"-like code example of network servers.
  16
+ * Building a simple chat, both server and client.
  17
+ * Building a very small asynchronous Websockets client.
  18
+
  19
+
  20
+## Covered versions ##
  21
+
  22
+This guide covers EventMachine v0.12.10 and 1.0 (including betas).
  23
+
  24
+
  25
+## Level ##
  26
+
  27
+This guide assumes you are comfortable (but not necessary a guru) with the command line. On Microsoft Windows™,
  28
+we recommend you to use [JRuby](http://jruby.org) when running these examples.
2
pete higgins
phiggins added a note May 25, 2011

Why recommend jruby for windows users? This isn't a knock against jruby, but the latest build of MRI from rubyinstaller.org works perfectly well with EM.

Because there were complains from Windows 7 users of amqp gem that EventMachine 0.12.10 fails to install on CRubies. 1.0.betas work fine. Both versions work well on JRuby.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
pete higgins phiggins commented on the diff May 25, 2011
docs/GettingStarted.md
((35 lines not shown))
  35
+This guide assumes you have one of the supported Ruby implementations installed:
  36
+
  37
+ * Ruby 1.8.7
  38
+ * Ruby 1.9.2
  39
+ * [JRuby](http://jruby.org) (we recommend 1.6)
  40
+ * [Rubinius](http://rubini.us) 1.2 or higher
  41
+ * [Ruby Enterprise Edition](http://www.rubyenterpriseedition.com)
  42
+
  43
+EventMachine works on Microsoft Windows™.
  44
+
  45
+
  46
+### With Rubygems ###
  47
+
  48
+To install the EventMachine gem do
  49
+
  50
+    gem install eventmachine
2
pete higgins
phiggins added a note May 25, 2011

To get EM 1.0.0-beta.3 as you show in your next example, you'd have to do gem install eventmachine --pre.

Right, this an overlook. We can fix it after merging this nasty 3K+ lines branch.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
James Tucker
Owner
raggi commented May 26, 2011

This is awesome, that you so much for digging in.

On the decision to go with 90 char width, I don't want to start painting bikesheds, but one point is, 80 chars fits better in the code boxes on github... take it or leave it, it's not that important. I'll generally format work I do to 80 anyway.

Michael Klishin

@tmm1 do you have anything you want me to update/change?

Aman Gupta tmm1 commented on the diff May 30, 2011
examples/guides/getting_started/01_eventmachine_echo_server.rb
... ...
@@ -0,0 +1,18 @@
  1
+#!/usr/bin/env ruby
  2
+
  3
+require 'rubygems' # or use Bundler.setup
  4
+require 'eventmachine'
  5
+
  6
+class EchoServer < EM::Connection
  7
+  def receive_data(data)
  8
+    send_data(data)
  9
+  end
  10
+end
  11
+
  12
+EventMachine.run do
  13
+  # hit Control + C to stop
  14
+  Signal.trap("INT")  { EventMachine.stop }
  15
+  Signal.trap("TERM") { EventMachine.stop }
2
Aman Gupta Owner
tmm1 added a note May 30, 2011

Are these signal handlers required? EM should shutdown cleanly on ctrl+c afaik.

It does shut down but with a backtrace-like output, for example:

^C/Users/antares/.rvm/gems/ruby-1.8.7-p334/gems/eventmachine-0.12.10/lib/eventmachine.rb:256:in `run_machine': Interrupt
    from /Users/antares/.rvm/gems/ruby-1.8.7-p334/gems/eventmachine-0.12.10/lib/eventmachine.rb:256:in `run'
    from ev.rb:3

I thought that less distractions Getting Started examples have, the better.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Aman Gupta tmm1 commented on the diff May 30, 2011
lib/eventmachine.rb
@@ -1219,20 +1240,26 @@ module EventMachine
1219 1240
   #    end
1220 1241
   #  end
1221 1242
   #
1222  
-  #  EM.kqueue = true if EM.kqueue? # file watching requires kqueue on OSX
  1243
+  #  # for efficient file watching, use kqueue on Mac OS X
2
Aman Gupta Owner
tmm1 added a note May 30, 2011

File watching will not work on OSX unless kqueue is enabled.

Aman Gupta Owner
tmm1 added a note June 15, 2011

Please add an explicit note to the docs about how file watching only works on OSX when kqueue is enabled.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
lib/eventmachine.rb
((10 lines not shown))
1560  
-        handler::const_set(:EM_CONNECTION_CLASS, Class.new(klass) {include handler})
1561  
-      end
1562  
-    else
1563  
-      klass
1564  
-    end
  1610
+              raise ArgumentError, "must provide module or subclass of #{klass.name}" unless klass >= handler
  1611
+              handler
  1612
+            elsif handler
  1613
+              begin
  1614
+                handler::EM_CONNECTION_CLASS
  1615
+              rescue NameError
  1616
+                handler::const_set(:EM_CONNECTION_CLASS, Class.new(klass) {include handler})
  1617
+              end
  1618
+            else
  1619
+              klass
  1620
+            end
3
Aman Gupta Owner
tmm1 added a note May 30, 2011

I prefer the old style here, as it does not require an indentation change if klass is renamed.

I am fine with either. This is how Emacs' Matz-authored ruby-mode indents if statements when used together with assignment.

Aman Gupta Owner
tmm1 added a note June 15, 2011

Please revert to old style here.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Michael Klishin

Any updates on this? Any other feedback? I begin to worry that will turn into yet another pull request that will be ignored forever.

.yardopts
... ...
@@ -1,3 +1,6 @@
1  
---exclude jeventmachine --exclude pure_ruby
2
Aman Gupta Owner
tmm1 added a note June 15, 2011

Can you put these excludes back?

Done in 5ad0de0

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
lib/eventmachine.rb
@@ -426,27 +394,31 @@ module EventMachine
426 394
   #  end
427 395
   #
428 396
   #  puts "We're starting the event loop now."
429  
-  #  EventMachine::run {
430  
-  #    EventMachine::connect "www.microsoft.com", 80, Redmond
  397
+  #  EventMachine.run {
  398
+  #    # hit Control + C to stop
  399
+  #    Signal.trap("INT")  { EventMachine.stop }
  400
+  #    Signal.trap("TERM") { EventMachine.stop }
1
Aman Gupta Owner
tmm1 added a note June 15, 2011

Please remove the signal handlers from the inline examples in eventmachine.rb

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Aman Gupta
Owner
tmm1 commented June 15, 2011

I will merge --squash this if you think its ready, as soon as the few minor things I commented on are fixed. Thanks for your hard work on these docs!

Michael Klishin

@tmm1 got it. I will clean up signals handlers and other minor things tomorrow. Thanks for quick response.

pete higgins

Typo: s/beings/begins

Also, "once object is" sounds less awkward as "once the object is".

pete higgins

Typo: s/amethod/a method/

Also, "a callable" in this document should probably be replaced with "an object that responds to #call" or something.

Michael Klishin

@tmm1, @phiggins I addressed all the points from last time. I think it is ready to be squash merged. Of course we are still only about 20% there and I will continue writing guides afterward, but at least w/o worrying about merging of this nasty 3-4K patch.

Aman Gupta
Owner
tmm1 commented June 17, 2011

Merge squashed in 38705c4

Aman Gupta tmm1 closed this June 17, 2011
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Showing 79 unique commits by 3 authors.

May 15, 2011
Michael Klishin Make test helper both 1.8.7 and 1.9.2 compatible 87cf47f
Michael Klishin Be n00b friendly and explain where rake/extensiontask comes from 3ccfea9
Michael Klishin Ignore Gemfile.lock 72d2aaf
Michael Klishin Ignore .yardoc/* d13e534
Michael Klishin Add YARD to Gemfile 3103d3f
Michael Klishin Initial version of .yardopts, uses Markdown a787182
Michael Klishin Initial version of the new README c71f564
Michael Klishin Axe old README 690dc27
May 16, 2011
dan sinclair switch from rdoc to yard 323ef5f
dan sinclair fixup some warnings from yard 48353f3
Michael Klishin Merge pull request #1 from dj2/documentation_revamp
Adding yard to Rakefile
e08011b
May 17, 2011
Michael Klishin Try wrapping lines at 90 characters 0aae586
Michael Klishin Move old (dusty, possibly outdated) docs to docs/old 52de285
Michael Klishin Old documentation is now under docs/old 45d1134
Michael Klishin Documentation guides index plus outline of Getting Started Guide 9819cec
dan sinclair move these to the top level where they typically live 6c885ed
dan sinclair add Eventmachine Introductions link; minor cleanups 8b2fffb
Michael Klishin Merge pull request #2 from dj2/documentation_revamp
Not sure what the best way to handle making small changes its?
3586789
Michael Klishin Unbreak blog posts list c31d1ec
May 18, 2011
Michael Klishin Move old examples to examples/old 1edf257
Michael Klishin Switch to YARD 0.7 that supports file includes: awesome for examples 7f40c54
Michael Klishin Add YARD 0.7.0 dependency in the .gemspec 926de43
Michael Klishin Initial bits of Getting Started guide, requires YARD 0.7+ e3d5128
dan sinclair add bluecloth to gemspec 8d26ae9
dan sinclair Defined in .gemspec, don't need in Gemfile 76ca7ff
dan sinclair restrict to .md docs 6f691ad
dan sinclair minor cleanups 8e0bdb8
May 22, 2011
Michael Klishin First example in the Getting Started guide is done 719e804
Michael Klishin Initial version of chat server example (in the Getting Started guide) d3a1fb9
Michael Klishin Add intermediate steps content for the Chat Server Example a78806d
Michael Klishin A typo 95413dc
Michael Klishin Improvements to the Getting Started Guide structure; Explain what it …
…doesn't demonstrate (intentionally)
4f9a975
Michael Klishin Wording, grammar 028684a
Michael Klishin Link to JRuby website f598ad5
Michael Klishin Add two more (not yet written) guides to the index 8b900a2
Michael Klishin Initial pass on porting the existing EventMachine::Connection documen…
…tation to YARD
fa09380
Michael Klishin Link to the (not yet written) TLS guide 1a4dfa6
Michael Klishin First shot at porting EventMachine (the module) documentation to YARD cac543a
May 23, 2011
Michael Klishin Improvements to EventMachine.run documentation
 * Explain what Unicorn, Passenger and Mongrel users should do if they want to
   run EventMachine event loop inside of their Web app.
f6978bd
Michael Klishin Update EventMachine.stop_event_loop documentation to explain where th…
…ose "connection termination callbacks" come from
a78404e
Michael Klishin Update EventMachine.connect documentation 0e747f6
Michael Klishin Update to EventMachine.start_server 77d597d
Michael Klishin Tiny update to EventMachine.add_timer documentation 8ca361a
Michael Klishin Tiny update to EventMachine.add_periodic_timer documentation b7ec259
Michael Klishin Rearrange EventMachine.defer documentation a bit 20eea13
Michael Klishin Update to EventMachine.enable_proxy documentation 6fad2a6
Michael Klishin Adhere to YARD's convention for #instance_methods and .class_methods 3b4de55
Michael Klishin Cosmetics a9ec292
Michael Klishin Update documentation for EventMachine.watch_file 320209a
Michael Klishin A typo 07461f6
Michael Klishin One more typo spotted by YARD 56fabaa
Michael Klishin Manually port dj2/eventmachine@707a0df 1036279
Michael Klishin Merge remote-tracking branch 'origin/master' into documentation_revamp d1390b9
Michael Klishin Another pass on EventMachine (the module, including methods) document…
…ation
6910df7
May 24, 2011
Michael Klishin Makes YARD actually pick up documentation on EventMachine::Connection cda8885
Michael Klishin Another pass on improvements to EventMachine::Connection documentation e39f482
Michael Klishin One more pass on EventMachine::Connection documentation 43a616b
Michael Klishin One more pass on EventMachine::Connection documentation 4b82c3b
Michael Klishin A typo e71c729
Michael Klishin More typos fa477ea
May 31, 2011
Michael Klishin Revert "Make test helper both 1.8.7 and 1.9.2 compatible"
This reverts commit 87cf47f.

Per request from @tmm1
e226d85
Jun 12, 2011
Michael Klishin Brush up BufferTokenizer documentation acb3e19
Michael Klishin Improve EventMachine::Channel documentation 5fdce25
Michael Klishin Cosmetics d17adef
Michael Klishin Improve EventMachine.Callback documentation 96d26fd
Michael Klishin EventMachine::FileWatch documentation update d3bbe5a
Michael Klishin Update EventMachine::FileStreamer documentation b173536
Michael Klishin Update EventMachine::Queue documentation 7a69f86
Jun 14, 2011
Michael Klishin Upgrade to YARD 0.7.2 a32e56a
Jun 16, 2011
Michael Klishin Put excludes back 5ad0de0
Jun 17, 2011
Michael Klishin A typo 6202866
Michael Klishin "a callable" => "an object that responds to #call" a26456f
Jun 18, 2011
Michael Klishin Grammar dad1449
Michael Klishin A typo 4e30913
Michael Klishin Add explicit note about kqueue 21b8cc9
Michael Klishin Revert Emacs code formatting here 4332599
Michael Klishin Remove this rdoc-ism 9c9c5a5
Michael Klishin Remove dead code e28f5eb
Michael Klishin Remove signal handlers from code examples d432f69
Something went wrong with that request. Please try again.