hoodwink.d enhanced



by why in inspect

So, ruby-doc has a new layout which is sensational. The pixel kickback to lo-res is almost wtf and it’s a jolly leap ahead.

Okay, well, it’s a good time to rethink our docs then. I don’t like RDoc’s frames, so I’ve been playing with a new RDoc template for Camping which flips classes using JavaScript. It’s kind of weak, but it’s kind of cool, too, I guess. I mean it’s great for packaging with a gem, but you can’t link to a class’ page. And methods don’t fit into the picture yet. (In action.)

To build:

 rdoc -q -t "Camping Documentation" -1 -T extras/flipbook_rdoc.rb \
   README lib/camping-unabridged.rb > doc/index.html

I’m not saying this template is the answer or anything, but it seems like there’s some taboo over RDoc templates (there’s only like three variations of the same template at large) and I’ll just say that this one took an hour or so.

said on 25 Jan 2006 at 19:16

“I want to enjoy this code”

said on 25 Jan 2006 at 19:38

I saw “[EVALUATION]” in the title and shuddered.

said on 25 Jan 2006 at 19:39

(Referring to a particular friend on ruby-talk / ruby-core.)

Regarding the ruby-doc.org change itself: hooray!!!! A million times better.

said on 25 Jan 2006 at 20:51

Okay, so what’s the best way to organize our RDocs?

How about some slidey thingies that drop the Class, file, and method listings out from the side or the top or something… (my preference would be files on the top left, the complete method listings on the top right, and the classes on the left).

And maybe there can be a floating navigation bar that lets you jump up and down between methods in a particular RDoc page. That’d be nice.

Hrmm… wish I had better HTML skills.

said on 25 Jan 2006 at 20:56

Thanks for the kudos on ruby-doc. Yes, the API docs need a facelift. I’m looking at RDog right now, which has a different template than the conventional rdoc HTML . It uses some JavaScript/DHTML sldy stuff I believe.

Need to get something up that I can poke at for a bit. It’s important, though that each class/module have it’s own URI , an it would be ideal f that were true for methods as well (though URI fragments might be enough)

said on 25 Jan 2006 at 21:05

Viewing the same page twice makes it disappear. Reverse these lines:

ele.style.display = 'block';
c.style.display = 'none';

It wouldn’t be very useful with something as small as Camping, but client-side live search would be pretty easy to implement.

said on 26 Jan 2006 at 04:38

cool for the new site for ruby-doc. but I clicked “10 Things Every Java Programmer Should Know About Ruby” at the very top of the page and got a tgz with a bunch of HTML pages. I think to put this on the front of the site like that, a PDF of that presentation should be made so it’s easier to access.

about the rdoc template, i agree the default one is not good. the following things bother me about that template:
  • it seems i can’t bookmark or send a link about a certain class. the address bar of the browser always displays http://camping.rubyforge.org/ and there doesn’t seem to be frames (probably IFRAM Es?)
  • when i got to “Module Camping::Models” (see, i can’t send you a link…) clicking on “Models” (link is javascript:showPage(‘Camping::Models’) ) nothing happens for me? many such links are dead for me ( javascript:showPage(‘Camping::Controllers::Base’) as well) so it’s difficult to evaluate more.
said on 26 Jan 2006 at 04:40

PS: using firefox 1.5 on win32

said on 26 Jan 2006 at 06:26

Would be nice if the docs where commentable. And building a diff file to update the source files.

said on 26 Jan 2006 at 06:49

zimbatim: what it needs it collaborative editing and cross-media scheduling of real-time examples with private messages and a calendar of events!

haha just kidding, i was reminded of this

comments would be nice though :)

said on 26 Jan 2006 at 06:59

Commentable docs sounds like a job for Hoodwink.d

said on 26 Jan 2006 at 07:27

why, see this and this for a possible solution to the link-ableness-problem.

said on 26 Jan 2006 at 10:27

zimbatm: what, you haven’t winked yet? Get with it, friend.

said on 26 Jan 2006 at 10:36

Huh… Actually, I’ve spent about all of 5 seconds thinking about RDoc thus far in the time I’m been playing with Ruby. I have to agree on the dislike of frames issue, so this is kinda nice. I’ll definately have to give this a try for FeedTools when I have the time.

said on 26 Jan 2006 at 15:25

phil: I’m not zimbatm, but a lot of us don’t wink because all we get are Internal Server 500 errors when we try.

said on 27 Jan 2006 at 02:33

looks nice!

said on 27 Jan 2006 at 06:20

Ah, nice!

Could certainly do with those URLs, though.

said on 27 Jan 2006 at 21:47

I played around with single-page templates using Javascript as well, but I have not touched it in months. Feel free to see if there is anything useful there: http://www.magical-cat.org/projects/ruedoc

said on 28 Jan 2006 at 00:02


said on 29 Jan 2006 at 07:24

rue, that is almost exactly what I was thinking of except I’d like to see a dropdown for sections on the page that floated on the side so you could easily jump around inside of it.

said on 29 Jan 2006 at 07:59

Can’t seem to get it to work though… ran setup.rb and installed the rue.rb template into the rdoc html templates folder and it tells me that the RDoc::Page::STYLE constant is uninitialized when called from write_style_sheet.

Any ideas?

said on 30 Jan 2006 at 20:25

I’m trying to understand what’s wrong with one-file-per-class without using frames.

CPA Ns layout for documentation seems just fine and they don’t have any frame-like madness.

What’s different about Ruby?

said on 01 Feb 2006 at 16:56

Sure, sure, that’s the goal. Just need to do a bit more RDoc hacking.

said on 02 Feb 2006 at 00:12

I think your layout is great, I just found it didn’t act right when I tried to right-click to open something in a different tab.

Isn’t that the whole problem with some of the AJAX sites—how do you bookmark pages when you are using javascript to change between states?

Comments are closed for this entry.