OCamldoc operates in two steps:
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.
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 =
object
(* ... *)
method generate module_list =
(* ... *)
()
(* ... *)
end
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.
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 =
object(self)
inherit Odoc_html.html
(** Return HTML code for the given text of a bar tag. *)
method html_of_bar t = (* your code here *)
initializer
tag_functions <- ("bar", self#html_of_bar) :: tag_functions
end
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.