You can install odoc and generate docs for your Dune project with:
opam update
opam install odoc
dune build @doc
Then, view the docs by opening _build/default/_doc/_html/index.html!
While release 1.4.0 has new features, it is mainly focused on stability and maintainability. See its full changelog here. The previous release, 1.3.0 last October, included a lot of new code. Because of concerns about its stability, we chose not to widely announce 1.3.0. So, this message serves as an announcement for both releases The full changelog for 1.3.0 can be found here.
New, error-recovering comment parser with helpful error messages.
Many bugfixes.
Compatibility with OCaml 4.08 (at least, the current beta releases).
Much more streamlined development process, cleaner code, more tests and CI, etc.
For now, we plan to continue improving the stability of odoc and the quality of its output. In the longer term, odoc has two significant goals:
To replace ocamldoc as OCaml’s primary documentation generator. At the core of odoc is a powerful cross-referencer, capable of fully handling the complexity of OCaml’s module system. Shortcomings in ocamldoc’s ability to resolve cross-references in complex projects were one of the original motivations for starting odoc.
To create centrally-hosted, cross-referenced, searchable online documentation for all the published packages in opam, a “docs.ocaml.org.”
Thanks to the odoc users and contributors, and happy documenting!
JaneStreet’s documentation has precisely been updated with this tool. If you are unhappy with the theme they choose you can simply:
opam install ocaml-manual base odig
odig odoc-theme list # spot the theme id you'd like
odig odoc-theme set --default mytheme
odig doc base
Regarding the OCaml API reference just odig doc ocaml and if you install the manual as above it will theme accordingly (see for example here for the manual themed according to odig.light — though the api reference that comes with the manual itself doesn’t, just use the odig generated one).
If you are still unhappy about the selection of themes just provide your own and distribute it via opam.
Can you make sure the latest version of odoc is installed (run odoc --version)? What is the dune version? Do you have any mli library files in your dune project?
That’s strange. Could you open an issue on odoc’s GitHub that includes a minimal project (ml/mlii and dune files) that has this issue?
BTW should dune build @doc also generate docs for dependencies?
No. That’s what odig should be used for. Once your package is installed locally (with for example dune install), you can use odig to generate its docs and that will include dependencies.
That’s strange. Could you open an issue on odoc’s GitHub that includes a minimal project (ml/mlii and dune files) that has this issue?
I’ll try.
No. That’s what odig should be used for.
I thought it should generate doc for both my libraries and their dependencies. Odig is not very convenient since it generate docs for all packages in my switch. It would be nice for development purposes to be able to generate docs for all libraries in the project and their dependencies. Cargo can do it AFAIK.
Ah, yeah, indeed. I wish it could generate docs for deps as well though. It’s inconvenient to generate separate docs for project with dune and dependencies with odig.
I don’t think that’s the problem of odig but you can have a look at this issue for a hack.
Regarding your desire, you’ll have to check with dune's developer but I think there are basically two approaches: either dune takes care of building all the docs itself or it only builds the docs for the libraries it builds and allows to specify an existing docset to link into, the technology for this is not there yet though, see this issue.
Thanks. Yes, I think it’s a problem and a purpose of dune rather than odig.
either dune takes care of building all the docs itself or it only builds the docs for the libraries it builds
Considering it already tracks the dependencies and builds the docs for local packages, it seems natural to merge these two and build docs for dependencies as well, but maybe there are some hidden issues I’m not aware about.
Please do create an issue on the Dune repo so this usecase can be tracked properly. There is still some work to be done on the dune/odoc rules, but it’s progressing.
The full changelog for 1.3.0 can be found here.