New pages for OCaml API

My CSS is based on udoc, so I think this is what they choose, maybe for a good reason (?). But I’m ok to try the background color.

Yes I see what you mean. Visually speaking, I’m not a great fan of indentation. For a module with many functions with short descriptions, it will give a harsh effect I think. But I can try. Or is there another possibility to make it stand out, instead of indentation?

Good, I put this on my list :wink:

OK, thanks for the explanation. It’s probably (hopefully) not too difficult to switch to odoc then, if we need it at some point.

Yes. It is followed by a comment relating to String_tag specifically (starting with (*). I think the typesetting of this comment should be improved but I don’t know how exactly: The color inside the comment stands out a lot while the constructor itself (not in comment) isn’t colored. If possible I would also get rid of comment tags (* and *).

I would favor indentation. Look for instance at the declaration of open_box in https://sanette.github.io/ocaml-api/Format.html : the text before val open_box ... and after it have almost the same indentation while the latter only refers to open_box while the former is a global, module-level comment. I would expect a declaration comment to be indented in order to start at the same column as the “l” in val or “p” in type.

BTW, if possible, having a link target for every type/val/submodule declaration would be nice too, like here: https://ocaml.janestreet.com/ocaml-core/latest/doc/base/Base/Container/index.html#val-iter

could you explain more precisely? For instance in
https://sanette.github.io/ocaml-api/Format.html#VALpp_set_formatter_out_channel
there are links to ‘formatter’ and ‘out_channel’ (these are automatically created by ocamldoc, I didn’t add anything here myself)

I have uploaded a new version (same link https://sanette.github.io/ocaml-api/)

  • background color for links in the TOC @Maelan
  • more indentation for value descriptions @Maelan, @grayswandyr
  • word wrapping long <pre> codes @grayswandyr
  • type table: remove (* and *), give more space to code wrt comments, diminish comment’s color @grayswandyr

searching is not ready yet… please wait
suggestions for dark theme welcome

1 Like

I meant that every declaration should also hold an anchor, with e.g. an <a name...> (not <a href...>). On the Jane Street example I gave, a sharp sign appears on the left of declarations and can be used to send a link to this or that precise declaration.

oh I see. In fact all declarations already have a id attribute, and can be reached this way (this is how the general index works) , for instance https://sanette.github.io/ocaml-api/Stream.html#EXCEPTIONFailure
All these links can be obtain by looking at the general index.
On the other hand, for adding the sharp sign, I don’t see how to do it without adding html elements to all values, which would be a bit heavy. If you think it really adds some value, we can do it I guess.

As far as I’m concerned, I think having access from the page itself to every anchor is useful. Going to the index for this is a bit cumbersome, I think. As a teacher of OCaml, I often have to refer students to this or that part of the API documentation, hence my request.

As far as I can see (I only know basic HTML and CSS), it would require a modification of the HTML… In which case, the sharp sign stuff would certainly not be especially more complex (e.g. copying Jane Street’s approach relying on the CSS attribute before), but this part is not really important to me. Any solution allowing to point easily to a given declaration would be ok.

Earlier this month @octachron worked on adding anchors-on-hover to the sections of the OCaml manual ( ocaml#9101 ). When that work gets merged (we are discussing the better approach to preserve good accessibility for the generated HTML), it probably wouldn’t be too hard to enable the same for the ocamldoc-generated documentation, and in any case it would be a good idea to follow a coherent style for that part.

1 Like

OK then I’m not touching this until you are converging

1 Like

(@steinuil) I have uploaded a new version with a basic search engine I just wrote. (same link https://sanette.github.io/ocaml-api/)

  • for each page, you can search values/modules
  • in the general index page, the search includes also the descriptions
  • search results are ranked by relevance

the downside is that each page now comes with an index of about 570Kb in the form of an index.js file. I’m kind of hoping that the browser will cache this, but I’m not sure. It would be maybe better to only load the index file on demand.

1 Like

it’s not exactly what you wanted, but the new search field makes it easier to find the href for a value

Really nice site! My opinions as a web dev: The only issue I see is viewing from mobile (iphone xs). The table of contents which lists all the modules looks to be split 50/50 in width and its offputting. The description is squished together. The background color (dark grey) is a little unappealing IMO, but overall really good!

1 Like

thanks a lot for the comments. I’ll try to improve the points you mention when I get the time

@chrisnevers, I have tried to improve the table. But html <table> are a nightmare to style properly, especially for mobiles (ul/li would have been much easier… maybe I should transform them…)

Drawback is that long words that caused problem like [CamlinternalFormatBasic] are now split. But one has to choose which one is worse, I guess.

Also, I have put some shadow in mobile mode, because the table of modules didn’t seem to be aligned with the header table of contents, (because of gradient color). Now it’s clearer I guess.

Lazy loading the index sounds good. You could try something like this (I haven’t tested this code):

let indexState = {
  status: 'NOT_LOADED'
};

document.getElementId('search-box').addEventListener('change', (ev) => {
  const query = ev.target.value;

  switch (indexState.status) {
  case 'NOT_LOADED':
    indexState = { status: 'LOADING', query };

    const script = document.createElement('script');
	script.src = '<index file>';
	script.addEventListener('load', () => {
	  indexState = { status: 'HAS_LOADED' };
	  search(indexState.query);
	});
	document.head.appendChild(script);
	break;

  case 'LOADING':
    indexState.query = query;
	break;

  case 'HAS_LOADED':
	search(query);
  }
})
1 Like

this code sounds good to me. In fact, I was thinking of doing something essentially identical :wink:

EDIT: just did it. It works! yay. Thanks! I just modified a little bit the code, and reacted to the click event, so that index loading is essentially unnoticeable by the user.

1 Like

I posted in the other thread on Ocaml documentation, but I forgot this one: so
there is a new version (with improved search engine, and all versions of ocaml 4.00-4.10) on
https://sanette.github.io/ocaml-api/
Please test it and report here (or on the other thread)

3 Likes

I order to be complete, I have just processed the “Compiler API”:
https://sanette.github.io/ocaml-api/compilerlibref/
This is a subset of modules that, starting from 4.08, have been put aside in the compilerlibref subdirectory of the manual.

Maybe it would be a good idea to do the same with the “Internal” modules: move them into a “internallibref” directory?

2 Likes