Hello, I took the excuse of providing a story for odoc at the OPAM level to toy and move a bit on the idea of simplifying package management by using the information OCaml stores in build artefacts and using OPAM files as the pivotal package metadata format.
In order to have a good comparison point for odoc generation I implemented a best-effort ocamldoc path which does per-package ocamldoc set generation (details [1]). It works pretty well in practice on quite a few packages, including the ocaml one. It also doesn't work at all on others. You can try it on your own opam switch by invoking: opam pin add -kgit opkg https://github.com/dbuenzli/opkg.git opkg ocamldoc opkg doc Do this in a 4.03 switch as the 4.02.* line was sadly systematically broken from a doc generation point of view. API docs can be found here http://erratique.ch/software/opkg/doc/ (or in `opkg doc opkg` of course). Here's a sample rendering done on a random selection of packages: http://erratique.ch/tmp/opkg-ocamldoc/var/cache/opkg/ocamldoc/ For ex. http://erratique.ch/tmp/opkg-ocamldoc/var/cache/opkg/ocamldoc/bos/index.html Other, simple but handy, commands you may want to try are: opgk guess-deps _build # Good hint that a brighter build future exists opkg changes bos opkg readme bos opkg homepage bos opkg issues bos opkg online-doc bos opkg doc bos If you want to know more about current packaging conventions, they are described in `opkg help packaging`. Note that they do not depend on the packages being OPAM managed (the OPAM file format is however reused). Using a software packager with a minimally decent release process like `topkg` implements them by default without the developer having anything special to do. Comments on this list welcome -- please do not file issues for now as the whole thing is very wip and moving, a lot of design details are not yet determined some of which will need time to mature. Daniel [1] Restricting generation to packages allows to avoid cross package name overwrites and outrageous generation times for the final link step. Given a package we just fish for the mlis installed in its (sub)libdir. We then look for a corresponding cmi at the same place and find out the digests of the cmis it imports. By looking up opkg's global index of compilation object digests their install location can be found and is used to generate the list of `-I` ocamldoc needs to compile the mli to an odoc file. Sometimes it works, sometimes it fails, for various different reasons. _______________________________________________ Platform mailing list [email protected] http://lists.ocaml.org/listinfo/platform
