OCaml Sphinx domain

Remember that these directives and roles are in a Sphinx domain, so you can either prefix them with ocaml: or set the default domain to "ocaml", either with the default-domain directive:

.. default-domain:: ocaml

or in the conf.py file:

primary_domain = "ocaml"

Examples below assume the default domain is set.

Directives

Values and types

.. val:: name

Document a value:

.. val:: v

    Some doc for *v*.

is rendered as:

val v

Some doc for v.

The value’s type can be documented using the :type: option:

.. val:: coords
    :type: (int * int) list

    The coordinates.
val coords: (int * int) list

The coordinates.

Refer to values using the val role.

.. type:: name

Document a type:

.. type:: t

    Some doc for *t*.
type t

Some doc for t.

The type’s parameters can be documented using the :parameters: option:

.. type:: t3
    :parameters: ('a, 'b, 'c)

    *t3* has three parameters.
type ('a, 'b, 'c) t3

t3 has three parameters.

The type’s manifest (i.e. if it is an alias for some other type) can be documented using the :manifest: option:

.. type:: int_list
    :manifest: int list

    A list of integers.
type int_list = int list

A list of integers.

The type’s kind (i.e. its constructors and record labels) can be documented using the :kind: option and the :constructor: and :label: doc fields:

.. type:: variant
    :kind: A | B of int

    A variant type.

    :constructor A: a

    :constructor B: b
type variant = A | B of int

A variant type.

Constructor A:a
Constructor B:b 
.. type:: record
    :kind: {a: int; b: float}

    A record type.

    :label a: a

    :label b: b
type record = {a: int; b: float}

A record type.

Label a:a
Label b:b

Refer to types using the typ role.

.. exception:: name

Document an exception:

.. exception:: MyException

    Some doc for *MyException*.
exception MyException

Some doc for MyException.

The exception’s payload can be documented using the :payload: option. The :label: doc field is used like for a type:

.. exception:: TupleException
    :payload: int * float

    With a tuple payload.
exception TupleException of int * float

With a tuple payload.

.. exception:: RecordException
    :payload: {a: int; b: float}

    With a record payload.

    :label a: a

    :label b: b
exception RecordException of {a: int; b: float}

With a record payload.

Label a:a
Label b:b

Refer to exceptions using the exn role.

Modules and module types

.. module:: Name

Document a module:

.. module:: MyModule

    Some documentation for *MyModule*.

    .. type:: t
module MyModule : sig

Some documentation for MyModule.

type t
end

The module can be documented as an alias using the :alias_of: option. There should be no contents in that case:

.. module:: MyAlias
    :alias_of: Original

    Some documentation for *MyAlias*.
module MyAlias = Original

Some documentation for MyAlias.

If the module get its contents from something else (e.g a module type, a functor application, etc.), this can be documented using the :contents_from: option:

.. module:: Contents
    :contents_from: SomeModuleType

    .. type:: t
module Contents : SomeModuleType = sig
type t
end

Refer to modules using the mod role.

.. module_type:: Name

Document a module type:

.. module_type:: MyModuleType

    Some documentation for *MyModuleType*.

    .. type:: t
module type MyModuleType = sig

Some documentation for MyModuleType.

type t
end

The :contents_from: option is also applicable to module types:

.. module_type:: Contents
    :contents_from: SomeModuleType

    .. type:: t
module type Contents = SomeModuleType = sig
type t
end

Refer to module types using the modtyp role.

Functors

.. functor_parameter:: Name

Document a functor parameter:

.. module:: Functor

    .. functor_parameter:: Parameter

        .. val:: n
            :type: int

    .. val:: m
        :type: int
module Functor : functor
(Parameter : sig
val n: int
end)
-> sig
val m: int
end
.. module_type:: FunctorType

    .. functor_parameter:: Parameter

        .. val:: n
            :type: int

    .. val:: m
        :type: int
module type FunctorType = functor
(Parameter : sig
val n: int
end)
-> sig
val m: int
end

The :contents_from: option is also applicable to functor parameters:

.. module:: Functor2

    .. functor_parameter:: Parameter
        :contents_from: SomeModuleType

        .. val:: n
            :type: int

    .. val:: m
        :type: int
module Functor2 : functor
(Parameter : SomeModuleType = sig
val n: int
end)
-> sig
val m: int
end

Roles

Some directives create entries in the general index and other indexes. You can avoid creating entries by using their :noindex: option. (That’s what we’ve secretly done above, to avoid polluting the indexes.)

:val:

Refer to a val: :val:`Linked.M.v2` creates this link: Linked.M.v2.

Notice that a dot is used to link to the contents of a module. To refer to the contents of a module_type, use a colon: :val:`Linked.MT:v3` produces Linked.MT.v3. And to refer to the contents of a functor_parameter, use a dollar sign: :val:`Linked.M.P$v1` produces Linked.M.P.v1.

To create shorter references, you can strip the path by prefixing it with a tilde: :val:`~Linked.M.v2` produces v2. When there is no ambiguity, you can also omit a prefix of the path: :val:`.M.v2` produces M.v2 and :val:`.v2` produces v2. The shortened path must start with either a dot, a colon or a dollar sign according to the kind of the previous (omitted) part: :val:`$v1` produces v1 and :val:`:v3` produces v3. You can combine both: :val:`~.M.v2` produces v2. This is consistent with the default Python Sphinx domain.

:typ:
:exn:
:mod:
:modtyp:

Referring to other kinds of elements follows the same rules:

module Linked : sig
module M : functor
(P : sig
val v1
end)
-> sig
val v2
type t2
exception E2
end
module type MT = sig
val v3
end
end

Indexes