Module Odoc_extension_registry

Odoc Extension Registry

This module provides a minimal registry for odoc tag extensions. It is kept separate to avoid circular dependencies between odoc_document and odoc_extension_api.

module Comment = Odoc_model.Comment
module Location_ = Odoc_model.Location_
type resource =
  1. | Js_url of string
  2. | Css_url of string
  3. | Js_inline of string
  4. | Css_inline of string

Resources that can be injected into the page (HTML only)

type support_file = {
  1. filename : string;
    (*

    Relative path, e.g., "extensions/admonition.css"

    *)
  2. content : string;
    (*

    File content

    *)
}

Support files that extensions want to output

type asset = {
  1. asset_filename : string;
    (*

    Filename for the asset, e.g., "diagram-1.png"

    *)
  2. asset_content : bytes;
    (*

    Binary content

    *)
}

Binary asset generated by an extension (e.g., rendered PNG)

type option_doc = {
  1. opt_name : string;
    (*

    Option name, e.g., "width"

    *)
  2. opt_description : string;
    (*

    What the option does

    *)
  3. opt_default : string option;
    (*

    Default value if any

    *)
}

Documentation for an extension option

type extension_info = {
  1. info_kind : [ `Tag | `Code_block ];
    (*

    Type of extension

    *)
  2. info_prefix : string;
    (*

    The prefix this extension handles

    *)
  3. info_description : string;
    (*

    Short description of what it does

    *)
  4. info_options : option_doc list;
    (*

    Supported options

    *)
  5. info_example : string option;
    (*

    Example usage

    *)
}

Documentation/metadata for an extension

type 'block extension_result = {
  1. content : 'block;
  2. overrides : (string * string) list;
  3. resources : resource list;
  4. assets : asset list;
    (*

    Binary assets to write alongside the HTML output. Use __ODOC_ASSET__filename__ placeholder in content to reference.

    *)
}

Result of processing a custom tag. We use a record with a polymorphic content type that gets instantiated with the actual Block.t by odoc_document.

type 'block handler = string -> Comment.nestable_block_element Location_.with_location list -> 'block extension_result option

Type of handler functions stored in the registry. The handler takes a tag name and content, returns an optional result. If None, the tag is handled by the default mechanism.

val handlers : (string, Obj.t) Hashtbl.t

The registry stores handlers indexed by prefix

val prefixes : (string, unit) Hashtbl.t

Registered prefixes for listing

val support_files : (string, support_file) Hashtbl.t

Support files registered by extensions

val register_handler : prefix:string -> 'block handler -> unit
val register_support_file : prefix:string -> support_file -> unit
val find_handler : prefix:string -> 'block handler option
val list_prefixes : unit -> String.t list
val list_support_files : unit -> support_file list
val prefix_of_tag : string -> string

Extract the prefix from a tag name (part before the first dot)

Code Block Handlers

Similar to custom tag handlers, but for code blocks like {@dot[...]}. Handlers can transform code blocks based on language and metadata.

type code_block_meta = {
  1. language : string;
  2. tags : Odoc_parser.Ast.code_block_tag list;
}

Metadata for code blocks, extracted from parser AST

type 'block code_block_handler = code_block_meta -> string -> 'block extension_result option

Type of code block handler functions. Takes metadata and code content, returns optional transformed result.

val code_block_handlers : (string, Obj.t) Hashtbl.t

Registry for code block handlers, indexed by language prefix

val code_block_prefixes : (string, unit) Hashtbl.t

Registered code block prefixes

val register_code_block_handler : prefix:string -> 'block code_block_handler -> unit
val find_code_block_handler : prefix:string -> 'block code_block_handler option
val list_code_block_prefixes : unit -> String.t list
val prefix_of_language : string -> string

Extract the prefix from a language tag (part before the first dot)

Extension Documentation

Extensions can register documentation that describes their options and usage. This is displayed by odoc extensions.

val extension_infos : (string, extension_info) Hashtbl.t

Registry for extension documentation

val register_extension_info : extension_info -> unit
val list_extension_infos : unit -> extension_info list