I am now working on the API part of it. Here is a first proposition: https://sanette.github.io/ocaml-api/
Of course it can be improved, and I’m asking for constructive comments, keeping in mind:
the design has to integrate well with the current design of ocaml.org
On the technical side, finally I didn’t use odoc because @octachron remarked that it could lead to issues when generating the PDF. Hence I only post-processed the html; but this is rather light, it takes about 2sec for about 380 files in the libref directory. Once odoc gets updated, we can think back.
Some precise questions:
in many pages there is room left on the sidebar, so we could implement a search engine. Would it be useful? Does someone know how to do it?
since the API is often next to the programmer’s editor, it would be easier to her eyes to adapt the color scheme. Do you favor a javascript button with something like “dark theme/light theme”?
About the search: yes it would be extremely useful, and Racket’s documentation has search in the sidebar which also works offline with static HTML which we could copy. It generates a simple index file which contains a list of tuples of keyword, link, and other information, and then uses some search functions to comb through it.
Hi, very cool. Is there a way to perform a line break when a line (indicating the type of a function for instance) is too long? See e.g. pp_set_formatter_out_functions in https://sanette.github.io/ocaml-api/Format.html#meaning .
Also, the lines enriching the definition of type stag with constructor String_tag in section https://sanette.github.io/ocaml-api/Format.html#tags do not render well, I don’t know if something can be done about this.
Your theme looks nice. I’d prefer a background color rather than underlining for hovered links (at least in the left column and in the table of contents). I think it would be more readable, but I may be wrong.
The description of values doesn’t look indented enough with respect to its declaration, for example here, it’s not obvious to my eye that the example snippets (set_margin 10; … and printf "@[…) are one level deeper than the value declaration that comes after (val pp_get_max_indent : formatter -> unit -> int).
@sanette, using odoc for generating the API documentation should be essentially fine? This part of the manual is essentially an if we are generating html, link those files; otherwise include those other files. Replacing the html branch with odoc generated documentation should work. It is probably more work, so your approach is also fine.
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.
