We are pleased to announce release 1.4.0 of odoc, the new, Dune-friendly documentation generator for OCaml and ReasonML.
Some sample output, which you can browse here:
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.
In summary, compared with 1.2.0, odoc now has:
- New appearance.
- Tables of contents on each page.
- Generation of docs in ReasonML syntax.
- Interop with BuckleScript.
- Parallel packaging for NPM and esy.
- 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!