Show HN: Omniref - a better search site for Ruby documentation | Hacker News Reader

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

omniref.com

110 pointstimr57 comments

Open articleView on HN

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

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

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

We need to give more love to symbol search - most are fine, but the query analyzer doesn't do well with all combinations. We'll add that one to the bug list.

Glad someone found the 404 page, at least. ;-)

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?

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.

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?

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

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.

Yep, that's it. Would love to just click the one from the results, then have that view. But if I have to then click the name on the right, that's fine too.

We're working on that right now, actually. We weren't sure that people would want it, though, so that's good feedback. ;-)

That looks perfect, would definitely be appreciated.

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.

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.

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

This!

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.

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

awesome! I cannot wait! :D sign me up for any beta action you got :P

Heh. We skimped a bit on the "beta" invite thing. Send me an email (addr is on my profile) and I'll let you know when it's ready.

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

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.

Ah. It seems that for some reason I searched by the gem name, which obviously came up with nothing.

Hm. You searched for rails, or something else?

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

Let us know if there's a bug.

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

doesnt take me to http://rubygems.org/gems/fuzzy_match

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

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

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.

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

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

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

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.

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.

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.

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!

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.

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

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.

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!

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

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

Vim users also want :)

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

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

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.

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.

Thank you, awesome, bookmarked :-)

Looks neat!

Would be nice to have the logo as a favicon.

Ohhhhhhhhhhhhhhhh yissssssssssssssssssss!

Can you do this for Rails too?

We've indexed every ruby gem, including rails.

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

If your gem is published, we'll pick it up automatically during the next index run. If not, we're thinking about adding the ability to index public repos -- but private ones are longer-term. What do you need?

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

:-)

Awesome!

pretty sweet!

Reply on news.ycombinator.com