Suggestions for ocaml documentation

done ! (well, only a PR :wink: )

8 Likes

Can we have the same thing for batteries?
I am a very big fan of the search by type signature thing.
Maybe the Jane Street people will be interested too, they have quite a lot
of open source libraries which are not easy to search into!

@UnixJunkie, of course, it is possible to transpose this to any library. It should not be very difficult. But it takes time… I’ll let you know if I can work into this.

This is very cool! It’s already been helpful for me.

A couple of things I noticed:

  • When I search int -> string, I get results like Unix.getservbyport : int -> string -> service_entry and Format.pp_print_as : formatter -> int -> string -> unit listed above some functions that return strings. Especially for immutable types, I’d care quite a lot about the return type more than the string match distance alone.

  • M.t types seem to be listed as t -> *, thus preventing searches such as Bytes.t -> string

good idea, I’ll try to implement this.

Mmm, this looks more complicated — at first sight, at least. I would like to keep a good tradeoff between features and simplicity of the code (the latter mainly for ensuring it’s fast enough on all computers)

1 Like

I’ve changed the ranking following this idea. Can you give it a try? (you might need to force reloading the page)

This is great, thanks!

maybe some special characters, like ^ and $, could be supported.
For example:
^int -> int: will match only type signatures which start like this
-> int$: would match only signatures which end like that.

this is now implemented, you may try it.

4 Likes

It just works ™. Fantastic!
https://sanette.github.io/ocaml-api/4.08/index.html

2 Likes

What I can do is replace all anonymous “t”'s by the fully qualified “Module.t” in the search index. This means that searching for “int ->t” would now produce no result. Would this be a good solution?

I think that would work. These t types are very common, and you’d always qualify them when searching anyways.

1 Like

The speed of the search is amazing! Especially compared with the modern websites.

2 Likes

OK this is now implemented. Can you try?

3 Likes

Works great and covers all my daily needs, thank you!

Anything else I could think of are probably trickier, like type variables and type equalities.

Type equalities like 'a 'b Result.t = 'a 'b result would be nice to cover but at least with Stdlib it seems easy to find what you are looking for without such logic.

Type variables might work with simply ignoring the variable altogether for search purposes, i.e. Bytes.t -> Seq.t gets you Bytes.to_seq : t -> char Seq.t and Bytes.to_seqi : t -> (int * char) Seq.t.

1 Like

This a bomb :boom:. Very nice. Thanks for this. :+1:

1 Like

Just some information about the PR to ocaml.org mentioned above. This PR is abandonned, it did not raise enough interest, maybe too big, or maybe just bad.
Instead I’ve recently proposed a much smaller PR https://github.com/ocaml/ocaml.org/pull/1124
which is just a new arrangement of the docs page, with links to the existing manual (which now resides in https://ocaml.org/releases/).

On the other hand the work on the manual itself continues, on https://sanette.github.io/ocaml-tutorial/index.html
I’m happy to announce that, although it first started only with Part I (Tutorials), it should now contain the whole manual. Of course it’s difficult for me to check every page of it, so comments are welcome!

9 Likes

That is awesome! Thanks.

Please do not give up, it is a huge improvement over the official manual. I personally keep a mirror of your pages locally for offline use, the API search is pure gold!

What if, for now, we check if this can be integrated into the ocamlverse. @bluddy what do you think?

5 Likes

I’d have no problem trying to integrate it, but I think integrating into the site’s jekyll structure could be painful, and since the docs would be in a corner of the site, they wouldn’t be as easily available.

@sanette, why not create an organization on github: say, ocamlapi? Migrate your repo to this organization. You’d then have the site ocamlapi.github.io which would be easy to find (and bookmark). I have to mention that I also love what you’ve done with the docs, including the API search stuff.

1 Like

@bluddy, @mseri, many thanks for your support. Don’t worry I’m not giving up :wink: As I said in the first PR, my ambition is to integrate this post-processing into the ocaml/manual dev. If this fails I’d be happy to try your suggestions.

4 Likes