Show HN: Omniref - a better search site for Ruby documentation

http://www.omniref.com

by timr • 13 years ago

110 57 13 years ago

montanalow4• 13 years ago

Tim & I are planning to spend quite a bit more time on this, what do you other devs want to see in documentation search? Full stack? Multi version? Comments? Examples? IDE integration? What would make your life better?

csmattryder2• 13 years ago

Some feedback I have, is that I would like the sidebar to have a view that was less 'cluttered'. I know what String#new does, so could I just view all the methods available - sans description? Like how ruby-doc does it, super fast to spot what I need to lookup and click it.

Another is that the sidebar seems to take up a fair bit of space (especially as I use a half-sized browser window).

I really want to see this flourish, it seems a lot faster than searching ruby-doc! Keep at it, guys! :)

timr18• 13 years ago

Thanks! Is this more like what you're looking for?

http://www.omniref.com/docs/ruby/stdlib/2.0.0-p247/classes/A...

We're still working out how to display the search results, but we definitely want to strip them down more. Thanks for the feedback.

derwiki2• 13 years ago

Enumerate options that are obscured by inheritance. For example, to look at:

http://www.omniref.com/?q=cache_action

I don't know what options are valid in `cache_action`. The "real" answer, AFAICT, is to keep walking up the source code until you find the AbstractWhatever that actually defines the options.

timr18• 13 years ago

Yeah, rails makes this as hard as possible to figure out, because everything is done dynamically by Hash arguments. Maybe we can do something like like link up the inheritance tree from the method?

atmosx2• 13 years ago

I would like to have code examples in many libraries. But I'm not sure how you could achieve this... Maybe linking stackoverflow related posts in some way.

timr18• 13 years ago

This is on the feature short-list. We actually had it in there early on, but we weren't happy with the quality, so we pulled it.

We're going to re-try with a different approach that we think will work better. It's definitely going to happen.

JonnieCache3• 13 years ago

Load the rdoc for all of rubygems/github into it. Like rdoc.info et al

timr18• 13 years ago

We already have all of the documentation for all of the current ruby gems, plus the ruby standard library. We don't yet have all versions of everything, but that's coming soon.

AFAIK, we're already more comprehensive than the existing sites, though.

william_hc2• 13 years ago

comments for sure. Could be as simple as disqus on endpoints like the angular docs.

jaredgrippe3• 13 years ago

It would be awesome if I could upload (or just post) my Gemfile to your site and be able to search only the gems I am using.

timr18• 13 years ago

I've wanted this since the beginning, so this is coming soon. ;-)

jaredgrippe3• 13 years ago

It would also be nice to use chrome's "tab to search" feature so I can just type: "omniref" [TAB] [query]

jc00ke• 13 years ago

This!

treystout• 13 years ago

I've always liked what Mercurial's docs were trying to do (http://hgbook.red-bean.com/read/customizing-the-output-of-me...) by having comments at every paragraph of their docs. It's done about 10% as well as it could be though. You almost want stackoverflow style questions to link to direct paragraphs or maybe even sentences.

Maybe overlaying something like rap genius' tools on existing docs is enough?

Looks really nice so far, but I don't use ruby so can't vouch for accuracy of search etc...

dljsjr• 13 years ago

This seems to be a Bryan O'Sullivan thing, as the online version of Real World Haskell looks the exact same.

http://book.realworldhaskell.org

yale• 13 years ago

Looking great. My only wish would be having a list of constants and methods in the sidebar after selecting a class or module.

timr18• 13 years ago

Thanks! We have this other document view that we're going to make more prominent in the coming days:

http://www.omniref.com/docs/ruby/stdlib/2.0.0-p247/classes/E...

The "preview" that shows up from search pages links to it, but it's definitely not obvious where/how. We'll fix that!

montanalow4• 13 years ago

Right now, the Table of Contents navigation is only visible on full documentation pages, but I'm working on some javascript to make it work in a nice way for the search results previews too. Also working on making it more obvious how to get to the full doc pages as well.

mckaym• 13 years ago

I also like APIdock. They show the version history of a method - http://apidock.com/rails/v3.0.0/String/camelize

YorickPeterse• 13 years ago

Looks neat!

emmett• 13 years ago

Improved crossreferences! The main problem with Rails docs today is that methods mention other methods by name, but there's no way to jump directly to that other method.

timr18• 13 years ago

It's pretty tough to always know the right method in the general case (e.g. method from another module), but we think have some ideas that we're working on that will greatly improve this.

If nothing else, we can trigger a search for methods with that name. We're going to do that very soon, actually.

atmosx2• 13 years ago

Thank you, awesome, bookmarked :-)

xacaxulu• 13 years ago

Ohhhhhhhhhhhhhhhh yissssssssssssssssssss!

znowi• 13 years ago

Very nice. One note though. When I look for "puts", I get OpenSSL::Buffering#puts when I'd expect Kernel#puts. "kind_of" gives me RSpec::Mocks::ArgumentMatchers#kind_of. I think you should assign proper weights.

timr18• 13 years ago

We've done a lot of work to weight things correctly (e.g. searching for "inject" does what you'd expect), but we definitely need to do more work on really common tokens like "puts".

We'll add those to our bad search list. Thanks for the feedback!

montanalow4• 13 years ago

We're looking at several other signals than tf/idf right now, but the really big improvements in quality will come from static & runtime analysis of all the publicly available ruby code for just this sort of case. I'll make sure these get added to our ever growing list of QA queries so we can make sure they improve.

william_hc2• 13 years ago

Looks solid. Set it up with Alfred.app right away. Looking forward to continued support!

immad2• 13 years ago

Can you do this for Rails too?

montanalow4• 13 years ago

We've indexed every ruby gem, including rails.

timr18• 13 years ago

http://www.omniref.com/?q=rails

:-)

immad2• 13 years ago

Awesome!

moonie1• 13 years ago

Is there some way I can view my own ruby project with this? like by pointing it at my github repo url/ssh url?

latortuga• 13 years ago

Anyone looking for functionality like this in a local, offline reference should check out YARD[1]. I (embarrassingly) only recently set it up to serve a set of my common gems and the ruby standard lib and it works and looks great.

[1] http://yardoc.org

timr18• 13 years ago

You should be careful with YARD -- we've found a number of bugs in it that lead to broken/missing documentation. The ruby standard library, for example, is missing huge chunks of its documentation if you use YARD instead of RDoc.

I very much wanted YARD to be a drop-in replacement for RDoc, but it's not quite there yet.

endgame• 13 years ago

Do you have an api? It would be nice to be able to make emacs do M-x ruby-apropos foo and pick something.

timr18• 13 years ago

We don't, but that's an interesting idea...I'm an emacs user, too.

derwiki2• 13 years ago

Vim users also want :)

Thibaut• 13 years ago

Well done! I've also been trying to improve Ruby's documentation with DevDocs: http://devdocs.io/ruby/

DanielRibeiro• 13 years ago

Wow, it works with symbols:

http://www.omniref.com/?q=+

http://www.omniref.com/?q=[]

http://www.omniref.com/?q=-

http://www.omniref.com/?q=*

Quick tip: You have this tiny styling issue here: http://i.imgur.com/4uxUuPO.png

timr18• 13 years ago

Urgh, thanks for the heads up. Making code blocks wrap correctly is non-trivial. We'll add that to the bug list.

crashandburn4• 13 years ago

Very nice. symbol hound just isn't that great so it's good that at least rubydocs can be searched properly for that spaceship and stuff. aw, can't find the stabby lambda, but at least you've got a nice 404 page :) http://www.omniref.com/?q=-%3E

ufmace• 13 years ago

I like the speed of the search and most of the layout. It could really use some kind of Table of Contents for the current entry, though.

For more fanciful ideas, it would be neat if there was a way to add links to particular paragraphs or sections so you can link to any relevant blog posts or StackOverflow questions that explain the intricacies of something in more detail. Especially if it was easy for readers to add them in themselves.

timr18• 13 years ago

We do have a ToC view for everything we index, it's just not totally obvious how to get to it right now (from search, click on the header in the preview window -- those links go to the view you want). For example:

http://www.omniref.com/docs/ruby/stdlib/2.0.0-p247/classes/A...

That said, you're totally right about this needing to be more visible, and we'll have something better for this in the next day or so.

"it would be neat if there was a way to add links to particular paragraphs or sections so you can link to any relevant blog posts or StackOverflow questions that explain the intricacies of something in more detail. Especially if it was easy for readers to add them in themselves."

We've had multiple requests for comments, so that's definitely going on our short list of new features. Thanks for the feedback, and let us know if you think of anything else.

mikeruby• 13 years ago

pretty sweet!

robblchen• 13 years ago

Would be nice to have the logo as a favicon.

Show HN: Omniref - a better search site for Ruby documentation

Related Stories