We added an experimental, incomplete and basic in-package search to staging.ocaml.org. 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.
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.
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ā.
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?
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. Iāll be adding that before releasing to the live site.
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 ).
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ā¦
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. 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.
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.
Iāll be adding that before releasing to the live site.
).