Suggestions for ocaml documentation

ok, then maybe I can just indicate “Extensions” in that box, and move the “Reference” part to a less prominently displayed part of the doc page.

I don’t want to have to repeat myself here so here’s the link to the discussion on my comments in the issue.

Here is how the “Tutorial” pages look like:

and the “API” page (only for 4.09 for now):

I have not touched the other pages (tools, extensions, etc.) yet, so at this moment these only link to the relevent chapters on the INRIA website

1 Like

I have added 4.10 to the github page for the Ocaml Tutorials:

https://sanette.github.io/ocaml-tutorial/

3 Likes

In fact I have also added all other chapters, but there is no table of contents yet
(because the entry page should eventually be the ocaml.org documentation page)

2 Likes

The “OCaml API”, which is the documentation for the standard library, is now complete for all versions 4.00–4.10, with a quick search field, on the demo site:

https://sanette.github.io/ocaml-api/

7 Likes

that’s awesome! thank you a lot for your work! :slight_smile:

An (even only approximate) support for searches by type signature would be nice!

good idea; I’ll think about it

@UnixJunkie, I have added type signature searching! does this sound good?

note: if you want to mix type signature and some keyword in the same search, you need to separate them with two spaces instead of one.

3 Likes

Ok, it does kind of work.
However, the list of results (especially their type signature portion) should be sorted by string distance to the type signature query; so that the ordering of results is more meaningful.
Also, if there are some exact matches, they could be highlighted in some way (like with a special background color or something).

1 Like

there is already a sort by string distance (more precisely substring distance). Could you give me a specific example?

EDIT: for instance, in https://sanette.github.io/ocaml-api/4.10/index.html
if you type “int -> int” you see there is some kind of sorting.
I agree it can certainly be improved.

1 Like

indeed the ranking algo was a bit buggy.
I just changed it. And implemented your suggestion to indicate exact matches

1 Like

Pretty cool work! A couple of minor remarks I got from navigating the pages a bit:

  • once we get to the docs for a specific version, I think it’s not very clear currently how to get back to the page with the list of all versions. My first attempt was to click on the big “ocaml” button, but it got me back to ocaml.org. The right solution is to click on the small link below (e.g “API version 4.10”). I think it could be made more visible; also, I find its name nonintuitive, granted that it makes me leave the 4.10 specific docs.
  • I wonder whether modules such as CamlInternalFormat, CamlInternalOO, Obj, … should be hidden, or at least segregated to a special section. Also, I wonder why Ocaml_operators is there since it just seems to be a piece of documentation. But maybe that’s something to report upstream. This page http://caml.inria.fr/pub/docs/manual-ocaml/stdlib.html seems to contain a “curated” list of the non-internal modules.
1 Like

thanks for testing! some explanations concerning your points

Concerning the Ocaml_operators page, I added it because it is not so straightforward to link from the API part of the manual to the rest of the manual, and it is quite useful to be able to link to the precedence table in the description of an operator definition. It might make sense to rewrite the link to this page to the precedence table in the language reference chapter and remove the page altogether.

I have just processed the “Compiler API”:
https://sanette.github.io/ocaml-api/compilerlibref/

So, I think that now the complete manual has been processed!
I will now work to integrate everything in the ocaml.org site.

3 Likes

Batteries would very welcome such a searchable OCaml documentation.
Our ocamldoc is here currently:
https://ocaml-batteries-team.github.io/batteries-included/hdoc2/

This is much better.
Thanks a lot, type searches are so useful!!!

it is certainly possible to adapt what I’m doing for the OCaml Manual/API as an ocamldoc plugin or postprocessor for any library.