View all changes

Odoc 1.4.0

We are pleased to announce release 1.4.0 of odoc, the new, Dune-friendly documentation generator for OCaml and ReasonML.

odoc-output|690x444

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:

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!

See full changelog

Changes

  • All parsing errors are now recoverable warnings (#238).
  • Page titles are now level-0 headings ({0 ...}), and top-level sections within a page are level-1 headings ({1 ...}) (#217, Rizo Isrof).
  • Don't render definitions of externals (#275, Nik Graf).
  • Disable programming ligatures (#248).
  • Rename --root-uri option to --xref-base-uri (#223, Rizo Isrof).
  • Deprecate redundant reference kind annotations (#246).

Additions

  • Preliminary compatibility with the current 4.08 beta releases (#309, Jon Ludlam).
  • Paragraph headings ({4 ...}) and subparagraph headings ({5 ...}) (#217, Rizo Isrof).
  • odoc support-files-targets command (#232).
  • Recommend bsdoc for using odoc with BuckleScript (#269, Leandro Ostera).

Bugs fixed

  • Improve breadcrumbs on .mld pages (#293, Daniel Buenzli).
  • Display tables of contents in nested module and class pages (#261, Rizo Isrof).
  • Uncaught exception when parsing references to operators with - in them, such as @-> (#178).
  • Incorrect parsing of references to operators with . in them, such as *. (#237).
  • Assertion failure when processing optional arguments in an .ml file with a type annotation, when that type annotation uses an alias of 'a option (#101).
  • Assertion failure when two modules with the same name are found by odoc (#148, Jon Ludlam).
  • Verbatim blocks ({v ... v}) can now only be terminated if the v} is immediately preceded by whitespace (#71, reported Daniel Buenzli).
  • Wrong column numbers for errors reported in comments (#227, #253).
  • Restore parsing of ocamldoc-style reference kind annotations (#244).
  • Ordinary type keyword instead of and rendered in HTML for mutually-recursive types (#105, reported @Fourchaux).
  • nonrec keyword not rendered (#249).
  • and not rendered for mutually-recursive modules, classes, and class types (#251).
  • Outer comment attached to a module rendered when the module is included (#87, Jon Ludlam).
  • Polymorphic variant constructor documentation not rendered (#176, reported @steinuil).
  • Variant constructor and record field documentation styled differently (#260, Jon Ludlam).
  • Sloppy keyword markup in HTML output (#319).
  • Rendering of multiple constraint clauses (#321).
  • Incorrect order of functor arguments (#261, Rizo Isrof).
  • odoc html option -o now creates the output directory if it does not exist #171, #264 Rizo Isrof).
  • odoc html-targets output now includes path prefix given through -o option (#173, Rizo Isrof).
  • Allow -I and -o options to refer to non-existent directories (#32, #170, Daniel Buenzli).
  • Make odoc compile-targets match odoc compile (#273, Daniel Buenzli).
  • odoc compile-deps does not work on .cmt files (#162, Daniel Buenzli).
  • odoc html-deps now scans for .odoc files recursively (#307, Daniel Buenzli).
  • odoc html-targets ignores stop comments (#276, Daniel Buenzli).
  • odoc html-targets and odoc html-deps segfault on .mld pages (#277, #282, Daneil Buenzli).
  • --theme-uri option not propagated to some subpages (#318, Thomas Refis).
  • Binary files not opened in binary mode (#281, Ulrik Strid).

Build and development

  • Always print backtraces for unhandled exceptions (3d10feb).
  • CI on macOS (#216, Leandro Ostera).
  • Test runner improvements (#266, Rizo Isrof).
  • Fix esy builds in Travis (#301, Jon Ludlam).
  • Don't require make in the esy build (#308, Leandro Ostera).
  • Get rid of some large GADTs (#292, Jon Ludlam).
  • Remove dependency on bos (#305, Daniel Buenzli).
  • Remove dependency on rresult (#306, Daniel Buenzli).
  • Remove dependency on bisect_ppx, previously present in development checkouts (#316).