In Rust, if I need to read the documentation of a new crate, I just go to docs.rs
In OCaml, say I’m interested in:
is there a standard centralized documentation place, or does each package do its own thing ?
Yes (it is pretty new!), you can use OCaml Packages · Browse Community Packages. Here is the online, centralized documentation for Bigstringaf Documentation · bigstringaf 0.9.0 · OCaml Packages
3 Likes
Perhaps the opam packages site could help out the new OCaml site by linking to the corresponding package there prominently so people who’re looking for docs can get them easily.
Another option is odig. It’s as simple as
opam install ocaml-manual odig
odig doc
to get nice rendered docs for all your installed packages. Or directly link to the package you want to read:
odig doc bigstringaf
Best part is very fast after the first usage (as it is all local), looks good, and it doesn’t cutoff sections of the docs as the centralized docs site does currently does.
1 Like
Thanks for the tool, it makes the doc look good!
I just have a few questions/remarks, not sure if they should be addressed somewhere else:
- is there a way to indicate a package is “obsolete” or “deprecated”? For Frama-C in particular, the packages
frama-c-baseandframa-c-e-acslare no longer relevant (everything is inframa-cnowadays), but other than the published date which is older, there is not much else to indicate to the casual reader that they should go elsewhere. Maybe we should update the package description ourselves in opam? - For
frama-c, the generated documentation for some reason only shows a single library,qed, and omits everything else. Not sure how we could help here.
It seems something is coming in opam 2.2.0 here
I’m not sure I undertand what you are seing here. I tried to install frama-c and that’s what I see on odig doc frama-c:
If you want to understand how odig generates docs from your package intalls see this page (also available via odig doc odig). If you use dune most of these things should happen automatically.
Thanks for the tips, we’ll use the deprecated tag when opam 2.2 lands.
Sorry, I think I replied to the wrong message, I was referring to the “OCaml Packages · Browse Community Packages” link, more specifically its generated page for Frama-C: Documentation · frama-c 26.0 · OCaml Packages, which only shows qed.
odig’s output is also not exactly what we intended; I think we may need to change some things in our documentation to make it clearer… 
This is autogenerated output because your package does not provide an index.mld file (details here). You should really consider adding and installing an index.mld to orient your users across the sizable set of frama-* packages. This index.mld should also be picked up by ocaml.org.
See for example brr’s index.mld, its source and rendered on ocaml.org
2 Likes