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?
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.
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.
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.
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!
@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.
this code sounds good to me. In fact, I was thinking of doing something essentially identical
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.
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)
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?