Hello,
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.
Homepage: http://erratique.ch/software/odig
Sample output: http://docs.mirage.io
The two main features of this release are:
odoc generated API documentation
The default documentation backend was changed from ocamldoc to odoc. Using 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
odocincarnation. - Fabrice Le Fessant for designing and implementing the essential
cmt[i]files. - 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:
http://docs.mirage.io/
http://docs.mirage.io/_ocamldoc/
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 M simply:
#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.
See:
http://erratique.ch/software/odig/doc/Odig.html#toplevel
https://github.com/dbuenzli/odig/issues/10
and 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.
Best,
Daniel