OCaml Task Force Policy area

OCamldoc API Ref

Why ?

Since ocaml is shipped with ocamldoc, most of documentation can be generated out of *.mli/*.ml files. This possiblity is very interesting, since it should help ocaml programmer to have a consistent bookshelf of OCaml library.

How ?

HTML

HTML generation is the most easy to handle. There is no name clash possibility and we can share date through the Applications/Programming section of doc-base (integrated bookshelf tools of debian).

Most of the package can generate ocamldoc HTML data (since it is a common way to share this kind of information).

This is a first step toward generating a consistent HTML based documentation.

Man

Manpages are quite common in C/Perl programming languages. Generating ocamldoc manpages is possible -- but not done for most of the package.

There is a high probability of name clash (just because there is a high possibility that a C function with the same name exists). One way to avoid name clash is to have a specific man section (just as Perl with .3pm).

Tools

ocamldoc-api-ref-config

This tool handle data that should be useful to generate required file to comply with coming OCaml Documentation policy. This tool behaves like *-config script.

Quick command line argument summary:

Usage:

ocamldoc-api-ref-config [--html-directory|--doc-base-generate] PACKAGE

Options:

Example:

$> ocamldoc-api-ref-config --html-directory libzip-ocaml-dev

/usr/share/doc/libzip-ocaml-dev/html/api

$> ocamldoc-api-ref-config --doc-base-generate libzip-ocaml-dev

debian/libzip-ocaml-dev.doc-base.ocamldoc-apiref

CDBS integration:

@OCamlDocApiRef@ is substitued in debian/*.in file by the $(shell ocamldoc-api-ref-config --html-directory $(pkg)) (maybe this will need to redesign the loop of *.in file in the CDBS file to check to what package belongs the *.in file)

This can be used in *.install.in to install documentation in the good directory.

The dependency for compiling the documentation (-I flags) must include all the directory generated in every package which are under the OCAML_STDLIB_DIR. A OCAML_OCAMLDOC_OCAMLFIND_FLAGS variable will allow to use ocamlfind to solve external dependency when invoking ocamldoc.

A rule will generate the .doc-base.ocamldoc-apiref for all packages defined in OCAML_OCAMLDOC_PACKAGES_DOCBASE variable.

A rule will generate the documentation and the .doc-base.ocamldoc-apiref for all packages defined in OCAML_OCAMLDOC_PACKAGES variable.