[Caml-list] [ANN] Odig 0.0.2

[Caml-list] [ANN] Odig 0.0.2

[Daniel Bünzli]

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` [0]. 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.

[0] https://github.com/ocaml-doc/odoc


# 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