Odig packaging conventions

Packages following these convention maximize odig's mining capabilities.

Package install structure

odig assumes all OCaml packages are installed in a library prefix called LIBDIR and have their distribution documentation installed in a prefix called DOCDIR. The values of these variables are automatically derived from the binary's installation path and can be overriden by environment variables, see odig conf --help for more information.

All direct subdirectories LIBDIR/P define a package name P whose corresponding documentation directory is assumed to be DOCDIR/P. The library path of the ocaml package is determined by ocamlc -where, not by LIBDIR/ocaml (for supporting opam system switches).

Metadata determination

Package metadata for package P is always read from a LIBDIR/P/opam file which must be a valid opam file. If present, the following fields are consulted and used by odig to define its metadata data fields:

• authors: the authors
• bug-reports: the issues URI
• depends: the package's declared dependencies (only informative)
• dev-repo: the repository URI
• doc: the online documentation URI
• homepage: the homepage URI
• license: license tags
• maintainers: the maintainers
• synopsis: the package synopsis
• tags: classification tags
• version: the version string

Distribution documentation

The distribution documentation for a package P is determined by caseless matching files in DOCDIR/P. The following matches are performed; multiple files are allowed to match, * denotes zero or more characters.

• DOCDIR/P/README*, determines readme files
• DOCDIR/P/CHANGE*, DOCDIR/P/HISTORY*, DOCDIR/P/NEWS*, determines change log files
• DOCDIR/P/LICENSE*, determines license files

odoc API documentation and manual

The API documentation and manual of a package P is generated by considering all cmi files in the hierarchy LIBDIR/P, the files in DOCDIR/P/odoc-assets and the files in DOCDIR/P/odoc-pages

For each cmi file if a corresponding cmti file is found at the same location it is used to generate the documentation of the module with odoc; if not, an existing cmt file is used and lacking this the cmi file is used as a last resort.

Any file in DOCDIR/P/odoc-assets is copied over in an _assets directory at the root of the package's generated API documentation.

Any .mld file in DOCDIR/P/odoc-pages is compiled with odoc to a manual page. In particular the file index.mld is used to define — modulo the chrome added by odig — the content of the package's landing page. If index.mld has a level 0 heading it is stripped.

If no index.mld is provided the package's API modules — those installed with cmi files and without __ in their name — are listed on the page.

Finally if the DOCDIR/ocaml-manual package exists it is copied over to the documentation set, linked (and possibly themed) from the package list page.

Odoc theme install structure

odig assumes themes are installed in a share directory called SHAREDIR. The value of this variable is automatically derived from the binary's installation path and can be overriden by an environment variable, see odig conf --help for more information.

Each subdirectory SHAREDIR/P/odoc-theme/T defines a theme identified by P.T. This subdirectory is expected to at least hold an odoc.css file with the theme layout for the odoc documentation set.

The theme can also contain a manual.css file in which case it is used to style the local copy of the OCaml manual held in DOCDIR/ocaml-manual (e.g. as installed via opam install ocaml-manual) and linked from the documentation set package list page.