[ANN] Odig 0.0.2

doc
announce

#1

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 odoc incarnation.
  • 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:

  1. No support to resolve ambiguities, if there is one you can’t load.
  2. No support to mandate specific load order for modules that rely on side-effects (this will be achieved via opam v2 extension fields).
  3. 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


The state of Ocamldoc and Odoc
#2

Congratulations on the release.

I tried the new version of odig but I am getting lots of warnings like below, is there a setting - perhaps an environment variable - that I am missing?
odig: [WARNING] zed: /home/foo/.opam/4.04.1+flambda/lib/zed/zed_utf8.cmi: no cmi found for AvlTree (c2a8a3c5b7be51599be424264b999be1)


#3

The warnings should mainly be due to bad package installs (there may be one case that needs to be silenced in the future for module aliases though). If you want the tool to be quieter see odig --help for options and env vars.


#4

Or libraries that use -pack which is not supported at the moment see https://github.com/dbuenzli/odig/issues/28


#5

there may be one case that needs to be silenced in the future for module aliases though

Indeed the packages were using module aliases.