Odig manual

odig helps you to access information about installed OCaml packages. The following shows basic odig usage, to understand how odig looks up that information see the packaging conventions.

In this manual we use odig itself as the example package.

Package metadata

Basic information about packages and their metadata is available with the pkg command.

odig pkg              # List recognized packages and their version
odig pkg odig --long  # Show odig's package full metadata

Metadata fields of packages can be queried individually with the show command:

odig show repo odig        # Show odig's repository address
odig show homepage odig    # Show odig's homepage address
odig show license odig     # Show odig's license(s) tags

A few URI metadata fields can be opened directly in your browser with the browse command:

odig browse homepage odig    # Open odig's homepage in your browser
odig browse issues odig      # Open odig's issue tracker in your browser
odig browse online-doc odig  # Open odig's online docs in your browser

Package distribution documentation

If the package installed them odig provides instant access to the the readme, change log and license files of a package via:

odig readme odig    # Show the readme of odig
odig changes odig   # Show the changes of odig
odig license odig   # Show the license of odig

If you want to access the file paths rather than the content use show:

odig show readme-files odig    # Show path to the readme of odig
odig show changes-files odig   # Show path the changes of odig
odig show license-files odig   # Show path the license of odig

Package odoc API documentation and manuals

To open the HTML package list or the page of a package in your browser use:

odig doc          # Package list
odig doc odig     # Doc for the odig package

In general if odig doc can't satisfy your request it will try to generate documentation for it unless prevented by the -n option. If the documentation for your request was already generated it will open it without checking if it's up-to-date, use the option -u to guarantee it's fresh.

odig doc -u       # Up-to-date package list and package docs
odig doc -u odig  # Up-to-date doc for the odig package

If you only want to generate the documentation use the `odoc` command:

odig odoc       # Generate API docs and manuals for all packages
odig odoc odig  # Generate API docs and manuals for the odig package

If the OCaml manual is installed as the ocaml-manual package (e.g. via opam install ocaml-manual), the local copy gets linked from the package list page.

odoc API documentation theme

The way new themes can be installed is described here.

The odoc theme used for odoc API documentation and manuals can be changed via the odoc-theme command:

odig odoc-theme list            # List available themes
odig odoc-theme default         # Show the default theme name

The default theme is used and restored whenever a documentation generation action occurs either through odig doc or odig odoc. It is defined in order:

  1. On the command line via the --odoc-theme option.
  2. In the ODIG_ODOC_THEME environment variable.
  3. In the ~/.config/odig/odoc-theme file.
  4. By odoc.default

The theme can be set on the current documentation set via the set action:

odig odoc-theme set odig.dark   # Use the theme odig.dark
odig odoc-theme set             # Use the default theme

However whenever a documentation generation action occurs this restores the default theme. If you want to persist your choice, use the --default option when you set the theme; this writes the theme name to ~/.config/odig/odoc-theme.

odig odoc-theme set --default odig.dark # Use theme and set as default

Publishing odoc documentation sets

In general the self-contained bundle of generated HTML files is available in:

$(odig cache path)/html

It does however have a few absolute symlinks that point outside the hierarchy so if you want to archive or copy the documentation set over to another machine make sure you follow the symlinks.

To publish the documentation for a list of packages $PKGS write an intro.mld file that briefly documents the purpose of the documentation set, it will be used as a preamble on the package list page. You can also define your own table of contents on this page in a toc.mld file whose content will end up in the nav.odoc-toc element; otherwise a default table of content is generated. Continue with:

export PKGS=...
opam switch create .
opam install odig $PKGS
odig odoc -v --odoc-theme=$MYTHEME \
             --index-title='My docset' --index-intro=intro.mld \
             --index-toc=toc.mld \
             --no-pkg-deps $PKGS

If the tag index on the package list page is a bit overkill for your documentation set, use the --no-tag-index option to suppress it.

Provided our webserver follows symlinks, you are now ready to publish your documentation set:

ln -s $(odig cache path)/html /var/www/my-docset

Publishing on GitHub

To publish your documentation set on GitHub you can use the gh-pages-amend tool distributed with odig. In the git repository for which you want to publish the documentation set invoke:

gh-pages-amend $(odig cache path)/html doc

this fetches the gh-pages on the origin remote, replaces the directory doc with the contents of $(odig cache path)/html by amending the last commit and pushes it back on the remote. The gh-pages branch is created if it does not exist and your current working directory is left untouched by the procedure.

See gh-pages-amend --help for more information and options.