The Final Pieces of the OCaml Documentation Puzzle


Jon Ludlam, University of Cambridge,
Gabriel Radanne, INRIA and
Leo White, Jane Street

Principles

Documentation should be...

  1. Correct
  2. Useful

Focus first on static html

from module signatures

Ocamldoc output

Odoc 1.5.1 output

Odoc master output

Compile/Link

Compile : .cmti / .cmt / .cmi -> .odoc

Requires dependent odoc files (same as standard ocaml compile dependencies)

Link : .odoc -> .odocl

Requires odoc files for everything in the package and all dependent packages

Generate: .odocl -> .html / .tex / man

No other dependencies

Challenges

  • Canonical/hidden modules
  • We don't expand module aliases...
  • ...except when they're the canonical module
  • Intermediate expansions
  • Shadowed items
  • Abstract modules/module types
  • References are more expressive than Paths
  • Dependently typed modules

Canonical modules 1

x.mli

type t

y.mli

type t = X.t

lib.ml-gen

(** @canonical Lib.X *)
module X = Lib__X

(** @canonical Lib.Y *)
module Y = Lib__Y

Canonical modules 2

x.mli

type t

y.mli

type t = X.t

lib__.ml-gen

(** @canonical Lib.X *)
module X = Lib__X

(** @canonical Lib.Y *)
module Y = Lib__Y

lib.mli

(* User-defined Lib module *)
module X = X
module Y = Y

The document layer

  • Results from link phase is a typed syntax tree
  • Requires 'thinking in OCaml' to traverse

Solution: transform to generic document IR

Items and annotated code

  • Traditional agnostic document representations:
    • Blocks (paragraphs, lists, tables, etc)
    • Inline (styling, links, etc)
  • Code representation:
    • Item (module, includes, values, methods, etc)
    • Annotated code (code with extra metadata)
  • New backends simply traverse values of these types

HTML output

Man page output

Future directions

  • OCaml manual, and deprecating ocamldoc
  • Search
  • docs.ocaml.org -- multiple versions
  • mdx

If you're interested, come and talk to us!

Odoc 2.0 Key Contributors

  • Jon Ludlam, Leo White, Jules Aguillon - new model
  • Gabriel Radanne - Document IR, new HTML and man renderers
  • Florian Angeletti - Latex renderer

Odoc 1.x contributors

Anil Madhavapeddy, Bobby Priambodo, Craig Ferguson, Daniel B├╝nzli, David Sheets, Florian Angeletti, Geoff Reedy, Jack Feser, Jeremie Dimino, Kate, Kevin Ji, Leandro Ostera, Luke Czyszczonik, Mohamed Elsharnouby, Nik Graf, Patrick Stapfer, Ricky Vetter, Rizo Isrof, Rudi Grinberg, Thibault Suzanne, Thomas Refis, Ulrik Strid, Ulysse, Yotam Barnoy, dhcmrlchtdj, mikaello