A Minimal Prototype of In-Package Search is on staging.ocaml.org

We added an experimental, incomplete and basic in-package search to staging.ocaml.org. :camel: The current prototype implementation uses an existing JavaScript library. That turned out to be the quickest / least-effort way to get something up and running while we work behind the scenes on something more refined.

On dream 1.0.0~alpha5 (latest) · OCaml Package (or any other package for which documentation has been successfully built by the documentation pipeline) you should see a search bar that allows you to search identifiers within the package.

The goal from our side is to bring a “minimum useful product” to you quickly. Please let us know if there are any problems or wishes for a “version 1.0.0” of the search.

If no show-stopping issues are uncovered, we’ll go ahead and apply a patch to the live site at ocaml.org by end of the week or early next week. :slight_smile:

Thank you @panglesd, @EmileTrotignon, and @art-w for enabling this! I spent surprisingly little time on the integration into staging.ocaml.org so far, so it’s going to be fun to see where this goes.

20 Likes

It works great ! Thanks !

I tried it out on the Dream package. I was a bit confused by the drop down and the dream package text desription. Initially I though the text description was part of the results. The drop down should either push the package description down or acquire some CSS (shadows?) to indicate that it is not part of the page but a kind of overlay?

P.S. Try searching on a term that brings up a lot of results on the Dream package. Example “send”.

1 Like

Dream is actually one of the packages that benefits (incrementally) least, as it’s a one-module package (deliberately)! But thank you :slight_smile:

I tried this out on Lwt. I think it should return the shortest result if there is an exact match with the short identifier name:

I originally saw some worse results, when I first typed this in the first result was Let_syntax.Let_syntax.Lwt_result.return.

But generally, this is very nice!

1 Like

I’m very happy with how the documentation viewing experience has improved. Thanks to everyone who worked on this, I love it.

Is it possible to run the docs UI locally, just as Racket does?

3 Likes

Is it possible to run the docs UI locally, just as Racket does?

It is possible to use odoc locally to render and consume documentation.

However, search has not yet been added to odoc.

This particular prototype of search is only on staging.ocaml.org at the moment.

3 Likes

To suplement to what @sabine mentioned, I would like to recommend odig.

odig is a very easy way to invoke odoc on your local machine. See Odig / Erratique

3 Likes

Agreed, it needs to be easier to see that this is the results box which is unrelated to the rest of the page content.

Indeed, I’ll tweak the ordering a bit with this in mind.

Thank you both!

ETA: changes addressing these two points will appear on staging in approx 15-20 minutes.

1 Like

Maybe my internet connection is slow but when I enter some search text, there is a pause before the results appear. That’s OK. But there should be some sort of feedback in the interim like a clock or a timer indicating that the search is being performed, otherwise it can feel confusing – and I would wonder is something going on?? Do I need to press the enter key?

1 Like

there is a pause before the results appear.

Does this only happen the first time when searching in a package you haven’t searched in before or always?

Either way, it makes sense. The prototype does load the search index only when you focus the search input, but doesn’t yet give the necessary visual feedback. :+1: I’ll be adding that before releasing to the live site.

Interesting. Searches performed subsequently are very fast and I would assume the index is being cached on the client browser?

the index is being cached on the client browser?

That is correct, the cache headers allow the client browser to cache the index indefinitely as it’s served under a hash-digest URL.

Regardless, your point is perfectly valid because the initial load should have visual feedback or I should make the page always load the index right away (which, however, may be a bit invasive for people who are only window-shopping for a package without the desire to search :smile:).

I think a visual wait feedback on first search for the package should be great.

Additionally the ocamldoc of a function is often a very useful thing. If you see hoogle.haskell.org they devote three lines per search result. We could do something similar so that we can see more details on what the function does perhaps? Here hover to show details of the ocamldoc might also be a good idea, or an expandable [+] ?

Basically the amount of space devoted to showing the ocamldoc of the function is not enough. Once you click on a result, you lose context and actually go to the method in question which is a penalty if that is not the result you wanted. So if you were able to see more information about the function without committing to navigate to it, it might also be useful…

3 Likes

Great work! Out of curiosity, is it using htmx?

1 Like

No, this prototype is built on the Typescript library MiniSearch, runs in the browser only, and uses plain JavaScript to render results into the DOM.

1 Like

Looking sweet!

@sabine, you may be interested to know that “touching” a search result on an iphone does not trigger the scrollTo action.

Being able to also search the type signatures would be the icing on the cake, if you need any ideas :grin:

1 Like

Basically the amount of space devoted to showing the ocamldoc of the function is not enough

Makes sense. The docstrings don’t always have the most important info at the front either (yet?).

For now, I’m adjusting the UI to give a full line to the docstring (at cost of smaller font-size - I think that’s okay, the font was relatively big). Additionally, when you keyboard-navigate to the item, it automatically expands all of the docstring.

When the upstream search in odoc is ready, we will revisit the UI and make further improvements.

Here’s another experimental thing: I added the ability to use the “S” key to focus the search input. Since we don’t do keypress on mobile, I placed a floating button for this functionality.

“touching” a search result on an iphone does not trigger the scrollTo

Thanks, mobile browsers seem to be a bit more fussy with scrolling. I think this last patch fixed it. If not, don’t hesitate to let me know.

Being able to also search the type signatures would be the icing on the cake

Indeed, that’s being worked on upstream in odoc. :slight_smile: It’s really good to see that people care about this feature because it means the time making a proper search to supersede this one is well spent.

1 Like