OCaml Task Force Policy area
OCamldoc API Ref
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.
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.
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).
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:
ocamldoc-api-ref-config [--html-directory|--doc-base-generate] PACKAGE
Output the directory name where the generated ocamldoc generated file should go
Generate debian/PACKAGE.doc-base.ocamldoc-apiref and output file created
Generate debian/PACKAGE.manpages (possible extension)
$> ocamldoc-api-ref-config --html-directory libzip-ocaml-dev
$> ocamldoc-api-ref-config --doc-base-generate libzip-ocaml-dev
@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.