Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Loading…

Documentation revamp #212

Closed
wants to merge 79 commits into from

5 participants

@michaelklishin

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.

@dj2

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

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

@dj2

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? :)

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.

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.

@dj2

Perfect. Thanks.

@dj2

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

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

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.

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

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
@phiggins phiggins commented on the diff
docs/GettingStarted.md
((35 lines not shown))
+This guide assumes you have one of the supported Ruby implementations installed:
+
+ * Ruby 1.8.7
+ * Ruby 1.9.2
+ * [JRuby](http://jruby.org) (we recommend 1.6)
+ * [Rubinius](http://rubini.us) 1.2 or higher
+ * [Ruby Enterprise Edition](http://www.rubyenterpriseedition.com)
+
+EventMachine works on Microsoft Windows™.
+
+
+### With Rubygems ###
+
+To install the EventMachine gem do
+
+ gem install eventmachine

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
@raggi
Owner

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.

@michaelklishin

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

@tmm1 tmm1 commented on the diff
...guides/getting_started/01_eventmachine_echo_server.rb
@@ -0,0 +1,18 @@
+#!/usr/bin/env ruby
+
+require 'rubygems' # or use Bundler.setup
+require 'eventmachine'
+
+class EchoServer < EM::Connection
+ def receive_data(data)
+ send_data(data)
+ end
+end
+
+EventMachine.run do
+ # hit Control + C to stop
+ Signal.trap("INT") { EventMachine.stop }
+ Signal.trap("TERM") { EventMachine.stop }
@tmm1 Owner
tmm1 added a note

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
@tmm1 tmm1 commented on the diff
lib/eventmachine.rb
@@ -1219,20 +1240,26 @@ module EventMachine
# end
# end
#
- # EM.kqueue = true if EM.kqueue? # file watching requires kqueue on OSX
+ # # for efficient file watching, use kqueue on Mac OS X
@tmm1 Owner
tmm1 added a note

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

@tmm1 Owner
tmm1 added a note

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))
- handler::const_set(:EM_CONNECTION_CLASS, Class.new(klass) {include handler})
- end
- else
- klass
- end
+ raise ArgumentError, "must provide module or subclass of #{klass.name}" unless klass >= handler
+ handler
+ elsif handler
+ begin
+ handler::EM_CONNECTION_CLASS
+ rescue NameError
+ handler::const_set(:EM_CONNECTION_CLASS, Class.new(klass) {include handler})
+ end
+ else
+ klass
+ end
@tmm1 Owner
tmm1 added a note

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.

@tmm1 Owner
tmm1 added a note

Please revert to old style here.

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

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 @@
---exclude jeventmachine --exclude pure_ruby
@tmm1 Owner
tmm1 added a note

Can you put these excludes back?

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
# end
#
# puts "We're starting the event loop now."
- # EventMachine::run {
- # EventMachine::connect "www.microsoft.com", 80, Redmond
+ # EventMachine.run {
+ # # hit Control + C to stop
+ # Signal.trap("INT") { EventMachine.stop }
+ # Signal.trap("TERM") { EventMachine.stop }
@tmm1 Owner
tmm1 added a note

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
@tmm1
Owner

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!

@michaelklishin

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

@phiggins

Typo: s/beings/begins

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

@phiggins

Typo: s/amethod/a method/

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

@michaelklishin

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

@tmm1
Owner

Merge squashed in 38705c4

@tmm1 tmm1 closed this
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Commits on May 15, 2011
  1. @michaelklishin
  2. @michaelklishin
  3. @michaelklishin

    Ignore Gemfile.lock

    michaelklishin authored
  4. @michaelklishin

    Ignore .yardoc/*

    michaelklishin authored
  5. @michaelklishin

    Add YARD to Gemfile

    michaelklishin authored
  6. @michaelklishin
  7. @michaelklishin
  8. @michaelklishin

    Axe old README

    michaelklishin authored
Commits on May 17, 2011
  1. @michaelklishin
  2. @dj2

    switch from rdoc to yard

    dj2 authored
  3. @dj2

    fixup some warnings from yard

    dj2 authored
  4. Merge pull request #1 from dj2/documentation_revamp

    Michael authored
    Adding yard to Rakefile
  5. @michaelklishin
  6. @michaelklishin
  7. @michaelklishin
  8. @dj2
  9. @dj2
  10. Merge pull request #2 from dj2/documentation_revamp

    Michael authored
    Not sure what the best way to handle making small changes its?
  11. @michaelklishin

    Unbreak blog posts list

    michaelklishin authored
Commits on May 18, 2011
  1. @michaelklishin
  2. @michaelklishin
  3. @michaelklishin
  4. @michaelklishin
Commits on May 19, 2011
  1. @dj2

    add bluecloth to gemspec

    dj2 authored
  2. @dj2
  3. @dj2

    restrict to .md docs

    dj2 authored
  4. @dj2

    minor cleanups

    dj2 authored
Commits on May 22, 2011
  1. @michaelklishin
  2. @michaelklishin
  3. @michaelklishin
  4. @michaelklishin

    A typo

    michaelklishin authored
  5. @michaelklishin

    Improvements to the Getting Started Guide structure; Explain what it …

    michaelklishin authored
    …doesn't demonstrate (intentionally)
  6. @michaelklishin

    Wording, grammar

    michaelklishin authored
  7. @michaelklishin

    Link to JRuby website

    michaelklishin authored
  8. @michaelklishin
  9. @michaelklishin
  10. @michaelklishin
  11. @michaelklishin
  12. @michaelklishin

    Improvements to EventMachine.run documentation

    michaelklishin authored
     * Explain what Unicorn, Passenger and Mongrel users should do if they want to
       run EventMachine event loop inside of their Web app.
  13. @michaelklishin

    Update EventMachine.stop_event_loop documentation to explain where th…

    michaelklishin authored
    …ose "connection termination callbacks" come from
  14. @michaelklishin
  15. @michaelklishin
  16. @michaelklishin
  17. @michaelklishin
  18. @michaelklishin
  19. @michaelklishin
  20. @michaelklishin
  21. @michaelklishin

    Cosmetics

    michaelklishin authored
  22. @michaelklishin
  23. @michaelklishin

    A typo

    michaelklishin authored
  24. @michaelklishin
  25. @michaelklishin
  26. @michaelklishin
Commits on May 23, 2011
  1. @michaelklishin
  2. @michaelklishin
  3. @michaelklishin
Commits on May 24, 2011
  1. @michaelklishin
  2. @michaelklishin
  3. @michaelklishin

    A typo

    michaelklishin authored
  4. @michaelklishin

    More typos

    michaelklishin authored
Commits on May 31, 2011
  1. @michaelklishin

    Revert "Make test helper both 1.8.7 and 1.9.2 compatible"

    michaelklishin authored
    This reverts commit 87cf47f.
    
    Per request from @tmm1
Commits on Jun 12, 2011
  1. @michaelklishin
  2. @michaelklishin
  3. @michaelklishin

    Cosmetics

    michaelklishin authored
  4. @michaelklishin
  5. @michaelklishin
  6. @michaelklishin
  7. @michaelklishin
Commits on Jun 14, 2011
  1. @michaelklishin

    Upgrade to YARD 0.7.2

    michaelklishin authored
Commits on Jun 15, 2011
  1. @michaelklishin

    Put excludes back

    michaelklishin authored
Commits on Jun 17, 2011
  1. @michaelklishin

    A typo

    michaelklishin authored
  2. @michaelklishin
  3. @michaelklishin

    Grammar

    michaelklishin authored
  4. @michaelklishin

    A typo

    michaelklishin authored
  5. @michaelklishin
  6. @michaelklishin
  7. @michaelklishin

    Remove this rdoc-ism

    michaelklishin authored
  8. @michaelklishin

    Remove dead code

    michaelklishin authored
  9. @michaelklishin
Something went wrong with that request. Please try again.