It’s my pleasure to announce odig 0.0.2.
odig is an ISC licensed library and command line tool to mine installed OCaml packages. It supports package distribution documentation and metadata lookups and generates cross-referenced API documentation for your opam switches.
The two main features of this release are:
odoc generated API documentation
The default documentation backend was changed from
odoc notably provides inter-package cross-references and correct output on functor heavy code bases.
As with the
ocamldoc backend, odig remains a dumb command driver, all the hard API doc generation work is being done by
odoc on the
cmt[i] files and credits should go to:
- Thomas Refis and Leo White for the current
- Fabrice Le Fessant for designing and implementing the essential
- David Sheets, Leo White and Jeremy Yallop for working through a lot of the initial hard details and implementing earlier prototypes.
To get API documentation for the packages installed in your current opam switch the following sequence of commands should be sufficient:
opam install odoc ocaml-manual odig odig odoc odig doc
If you are a packager consult
odig help packaging to understand how
odig generates API documentation using
odoc and other conventions to provide a good odig experience to the users of your package.
This is the last release of
odig that will provide the
ocamldoc backend. If you are interested in improving
odoc's output by comparing with what ocamldoc gave on your package this is the time to do it. This can be done here:
or, if your package is not listed there with
odig ocamldoc PKG && odig odoc PKG && odig doc --compare PKG. File any issue on the
odoc tracker, but please make sure it’s not already reported, we are already aware of some problems.
Experimental data-driven toplevel loaders
This release adds experimental toplevel loaders. The idea here is to kill the general need for
.ocamlinit files in your projects and not bother you having to know in whichever package and/or archive a particular module you need might be tucked.
In order to load any toplevel module
#use "odig.top";; Odig.load "M";;
this will lookup in your build directory and/or in the package install base and load appropriate dependencies by simply consulting the OCaml compiled object files (no
META file are involved in this process).
The loaders are not perfect yet, the main current limitations are:
- No support to resolve ambiguities, if there is one you can’t load.
- No support to mandate specific load order for modules that rely on side-effects (this will be achieved via opam v2 extension fields).
- For now they are also too slow on some modules with many deps (e.g.
Odig.load "Core"). However the load time is entirely reasonable on small and medium scale libraries (e.g.
Odig.load "Irmin_mem"). The very first load might be a bit slow though.
Odig.help () for more details. Except for failures due to ambiguous resolutions, feedback and concrete failures/problems report are welcome on
odig's issue tracker.