New pages for OCaml API

Community
21

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
22

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

23

@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.

24

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
25

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
26

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
27

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
28

This is pretty nice! Few remarks:

  • As usual for these ā€œgood lookingā€ designs, itā€™s a bit small for people-without-perfect-eyesight, and the font is not the most legible. I think odoc has converged towards a look that pleases everyone, what about using that one ?
  • The Initial index is not the one used in the manual: it includes modules such as CamlInternatlFormat.
  • You forgot most of compilerlibs

Otherwise, good work. I like the version index.

29

Thanks for testing!
I would like to apply your suggestions, but could you be a bit more specific?:

30

For the last 2 questions:

31

I checked that there are the same number of files in https://sanette.github.io/ocaml-api/compilerlibref/ as in https://caml.inria.fr/pub/docs/manual-ocaml/compilerlibref/, so I believe all files have been processed. Most probably not all of them are indexed in the index.html file.

32

Btw, it seems that some files are missing in the INRIA repository, for instance in
https://caml.inria.fr/pub/docs/manual-ocaml/compilerlibref/Consistbl.Make.html
the links to the Set, Map, and Tbl modules are broken.

33

this part is very difficult, Iā€™d be happy to have more feedback. On my laptop, when I open with Firefox fonts are huge (too large to my taste) while with Chromium I find it right.

If I compare for instance the page Buffer to the current discuss.ocaml.org page I think that my fonts are slightly larger (for the same ā€˜officialā€™ size = 15px. But my font is serif, which, I agree, is maybe more difficult to read)

34

It would help if you could indicate a module that is not accessible

35

All of typing/, middle_end/, lambda/, bytecomp/, asmcomp/, etc.

Basically, most of the compiler is not there. Seems like the official index only contains compiler-libs.parsing, and not the other sublibraries.

36

to be clear, is what is missing already missing in
https://caml.inria.fr/pub/docs/manual-ocaml/index.html
or only missing in my new version?

37

The compiler-libs documenation was picked at a time were the the stdlib and the compiler-libs shared essentially the same space (and index) in both the web and pdf version of the manual. Thus only few modules were added, and mostly the modules that were the more useful for ppx writer. Now that the stdlib and compiler-libs are properly separated, it would be nice to generate documentation for the whole compiler-libs for the web version indeed.

1 Like
38

Iā€™m of course OK to include them as soon as they are ready. On my side, I prefer to stick to the html files that are currently bundled in the Inria repo.

2 Likes
39

I agree that sticking with the existing manual is the right path.

40

I have uploaded a larger version. Hope you find it easier to read.

1 Like