[BUG][Doc] Many broken links in js_of_ocaml documentation

[balat]

A lot of links (all ?) to js_of_ocaml documentation are broken:
https://ocsigen.org/js_of_ocaml/latest/api/Dom_html
https://ocsigen.org/js_of_ocaml/latest/api/Js#VALstring
https://ocsigen.org/js_of_ocaml/latest/api/Dom_events#VALlisten
https://ocsigen.org/js_of_ocaml/latest/api/Js_of_ocaml_lwt.Lwt_js_events
https://ocsigen.org/js_of_ocaml/latest/api/Lwt_js_events#VALclick
https://ocsigen.org/js_of_ocaml/latest/api/Lwt_js_events#VALclicks
https://ocsigen.org/js_of_ocaml/latest/api/Lwt_js_events#VALmousedowns

[hhugo]

Likely the consequence of switching to odoc as well as splitting the project in multiple libraries.
Links now have a different format:
https://ocsigen.org/js_of_ocaml/latest/api/<opam-package-name>/<library-name>/<module>

https://ocsigen.org/js_of_ocaml/latest/api/js_of_ocaml/Js_of_ocaml/Dom_html
https://ocsigen.org/js_of_ocaml/latest/api/js_of_ocaml/Js_of_ocaml/Js#val-string
https://ocsigen.org/js_of_ocaml/latest/api/js_of_ocaml/Js_of_ocaml/Dom_events#val-listen
https://ocsigen.org/js_of_ocaml/latest/api/js_of_ocaml-lwt/Js_of_ocaml_lwt/Lwt_js_events
https://ocsigen.org/js_of_ocaml/latest/api/js_of_ocaml-lwt/Js_of_ocaml_lwt/Lwt_js_events#val-click
https://ocsigen.org/js_of_ocaml/latest/api/js_of_ocaml-lwt/Js_of_ocaml_lwt/Lwt_js_events#val-clicks
https://ocsigen.org/js_of_ocaml/latest/api/js_of_ocaml-lwt/Js_of_ocaml_lwt/Lwt_js_events#val-mousedowns

I'm guessing the links come from the doc of other ocsigen projects (like eliom)

[hhugo]

path generated by odoc are different in the following way:

• anchors are different (e.g. #val-string vs #VALstring)
• paths are prefixed by the name of the opam package (e.g. api/js_of_ocaml-lwt vs api/optional-sub-project)
• hierarchical structure (Js_of_ocaml/Dom_html/class-type-element/index.html vs Dom_html.element-c.html)

We should be able to fix html_of_wiki to support odoc.
The main change will be in api.ml to accommodate the change in anchors and paths.

We need a way a decide what api structure to use (odoc vs ocamldoc). Should we introduce a new extentions or just allow new parameters in the a_api one ?

Other than that, subproject will be mandatory for js_of_ocaml references with an explicit project=js_of_ocaml.

Here is an example of what we could get

<a_odoc_api project=js_of_ocaml package=js_of_ocaml-lwt| Js_of_ocaml_lwt/Lwt_js_events.click >>
<a_odoc_api package=js_of_ocaml-lwt| Js_of_ocaml_lwt/Lwt_js_events.click >>

@balat, what do you think ?

[jonludlam]

We're planning on adding a CLI util to odoc to map from a reference (ie., what you'd find in a doc comment, like (** {!Foo.Bar.baz} *)) to a URL. Would this be useful? The tool will require the relevant odoc files to have been built and their paths supplied as include arguments - there are some details on the issue

[hhugo]

@jonludlam, I think this will be useful long term

[hhugo]

@balat, I've started some experiment in https://github.com/ocsigen/html_of_wiki/tree/hhugo-odoc-support

[balat]

@balat, what do you think ?

Great news! Thank you for experimenting that!

I don't really have a preference.

I suppose that one day we will switch completely to odoc, as supporting the two backends will complicate things.
This may influence the choice.

I'd be happy to switch the whole website to odoc, even if it makes all URLs change ...
Do you think we can have something well integrated to the current web site and keep all html_of_wiki's features?

[hhugo]

I currently don't know how to well integrate the odoc api with the current website, see #855 for a possible solution.

Regarding feature parity, I don't have a good grasp on what they are.
Cross project links that include versioning is most likely not supported by default.

[hhugo]

I've fixed links in js_of_ocaml, eliom, tyxml, tuto