15.3 Custom generators

15.3.1. The generator class
15.3.2. Handling custom tags

OCamldoc operates in two steps:

  1. analysis of the source files;
  2. generation of documentation, through a documentation generator, which is an object of class Odoc_args.class_generator.

Users can provide their own documentation generator to be used during step 2 instead of the default generators. All the information retrieved during the analysis step is available through the Odoc_info module, which gives access to all the types and functions representing the elements found in the given modules, with their associated description.

The files you can used to define custom generators are installed in the ocamldoc sub-directory of the OCaml standard library.

15.3.1 The generator class

A generator class is a class of type Odoc_args.doc_generator. It has only one method

generator : Odoc_info.Module.t_module list -> unit

This method will be called with the list of analysed and possibly merged Odoc_info.t_module structures. Of course the class can have other methods, but the object of this class must be coerced to Odoc_args.doc_generator before being passed to the function

Odoc_args.set_doc_generator : Odoc_args.doc_generator -> unit

which installs the new documentation generator.

The following example shows how to define and install a new documentation generator. See the odoc_fhtml generator (in the Ocamldoc Hump) for a complete example.

class my_doc_gen =
    (* ... *)

    method generate module_list =
      (* ... *)

    (* ... *)

let my_generator = new my_doc_gen
let _ = Odoc_args.set_doc_generator (my_generator :> Odoc_args.doc_generator)

Note: The new class can inherit from Odoc_html.html, Odoc_latex.latex, Odoc_man.man, Odoc_texi.texi or Odoc_dot.dot, and redefine only some methods to benefit from the existing methods.

15.3.2 Handling custom tags

Making a custom generator handle custom tags (see 15.2.5) is very simple.


Here is how to develop a HTML generator handling your custom tags.

The class Odoc_html.html inherits from the class Odoc_html.info, containing a field tag_functions which is a list pairs composed of a custom tag (e.g. 'foo') and a function taking a text and returning HTML code (of type string). To handle a new tag bar, create a HTML generator class from the existing one and complete the tag_functions field:

class my_gen =
    inherit Odoc_html.html

    (** Return HTML code for the given text of a bar tag. *)
    method html_of_bar t = (* your code here *)

      tag_functions <- ("bar", self#html_of_bar) :: tag_functions

Another method of the class Odoc_html.info will look for the function associated to a custom tag and apply it to the text given to the tag. If no function is associated to a custom tag, then the method prints a warning message on stderr.

For other generators

As for the HTML custom generator, you can define a new LaTeX(resp. man) generator by inheriting from the class Odoc_latex.latex (resp. Odoc_man.man) and adding your own tag handler to the field tag_functions.