Graphviz/DOT Extension for odoc

This extension adds support for Graphviz diagrams using the DOT language in odoc documentation. Graphviz is a powerful graph visualization tool that can render complex node-edge diagrams.

Installation

opam install odoc-dot-extension

Once installed, the extension is automatically loaded by odoc.

Usage

Use the {@dot[...]} tag to embed Graphviz diagrams:

{@dot[
digraph {
    A -> B -> C
}
]}

Examples

Simple Directed Graph

digraph G {
    A -> B
    A -> C
    B -> D
    C -> D
}

With Labels and Styling

digraph {
    node [shape=box, style=filled, fillcolor=lightblue]

    start [shape=circle, fillcolor=green, label="Start"]
    end [shape=doublecircle, fillcolor=red, label="End"]

    start -> process1 [label="begin"]
    process1 -> decision [label="check"]
    decision -> process2 [label="yes"]
    decision -> end [label="no"]
    process2 -> end [label="done"]
}

Undirected Graph

graph {
    a -- b -- c
    b -- d
    c -- e
    d -- e -- f
}

Subgraphs and Clusters

digraph {
    subgraph cluster_0 {
        label="Process A"
        style=filled
        color=lightgrey
        a0 -> a1 -> a2
    }

    subgraph cluster_1 {
        label="Process B"
        color=blue
        b0 -> b1 -> b2
    }

    start -> a0
    start -> b0
    a2 -> end
    b2 -> end
}

Record Shapes (Data Structures)

digraph {
    node [shape=record]

    struct1 [label=" left| mid| right"]
    struct2 [label=" one| two"]
    struct3 [label="hello\nworld|{b|{c| d|e}|f}|g|h"]

    struct1:f1 -> struct2:f0
    struct1:f2 -> struct3:here
}

Finite State Machine

digraph FSM {
    rankdir=LR
    node [shape=circle]

    start [shape=point]
    q0 [label="q₀"]
    q1 [label="q₁"]
    q2 [label="q₂", shape=doublecircle]

    start -> q0
    q0 -> q0 [label="0"]
    q0 -> q1 [label="1"]
    q1 -> q0 [label="0"]
    q1 -> q2 [label="1"]
    q2 -> q2 [label="0,1"]
}

Binary Tree

digraph Tree {
    node [shape=circle]

    8 -> 4
    8 -> 12
    4 -> 2
    4 -> 6
    12 -> 10
    12 -> 14
}

Options

The extension supports the following options:

• layout - Graphviz layout engine: dot (default), neato, fdp, sfdp, circo, twopi, osage, patchwork
• width - CSS width (e.g., 500px, 100%)
• height - CSS height
• format - Output format: omit for client-side JS, or png/svg for server-side rendering (requires graphviz CLI tools)

Layout Example

Different layout engines produce different arrangements:

{@dot layout=circo[
digraph {
    a -> b -> c -> d -> e -> a
}
]}

digraph {
    a -> b -> c -> d -> e -> a
}

How It Works

By default, diagrams are rendered client-side using the Viz.js library (a WebAssembly port of Graphviz) loaded from a CDN. The extension injects the necessary <script> tags into the HTML output.

For server-side rendering, install the graphviz package and use format=png or format=svg.

DOT Syntax Reference

DOT syntax basics:

• Directed graph: digraph \{ ... \}
• Undirected graph: graph \{ ... \}
• Edges: A -> B (directed) or A -- B (undirected)
• Node attributes: A [label="text", shape=box]
• Edge attributes: A -> B [label="edge", style=dashed]

See the DOT language documentation for the complete syntax reference.