jon.recoil.org
A graphviz extension for odoc
Add documentation for odoc extension plugins
Add index.mld files with usage examples for each extension:
- mermaid: Flowcharts, sequence diagrams, state diagrams, etc.
- msc: Message Sequence Charts for protocol documentation
- dot: Graphviz/DOT diagrams for graphs and trees
- admonition: Note, warning, tip, important callout blocks
- rfc: IETF RFC citations with automatic linking
Each extension now has its own documentation page demonstrating
the syntax and showing live rendered examples.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
+191
index.mld
+191
index.mld
···
1
+
{0 Graphviz/DOT Extension for odoc}
2
+
3
+
This extension adds support for {{:https://graphviz.org/}Graphviz} diagrams
4
+
using the DOT language in odoc documentation. Graphviz is a powerful graph
5
+
visualization tool that can render complex node-edge diagrams.
6
+
7
+
{1 Installation}
8
+
9
+
{[
10
+
opam install odoc-dot-extension
11
+
]}
12
+
13
+
Once installed, the extension is automatically loaded by odoc.
14
+
15
+
{1 Usage}
16
+
17
+
Use the [{@dot[...]}] tag to embed Graphviz diagrams:
18
+
19
+
{v
20
+
{@dot[
21
+
digraph {
22
+
A -> B -> C
23
+
}
24
+
]}
25
+
v}
26
+
27
+
{1 Examples}
28
+
29
+
{2 Simple Directed Graph}
30
+
31
+
{@dot[
32
+
digraph G {
33
+
A -> B
34
+
A -> C
35
+
B -> D
36
+
C -> D
37
+
}
38
+
]}
39
+
40
+
{2 With Labels and Styling}
41
+
42
+
{@dot[
43
+
digraph {
44
+
node [shape=box, style=filled, fillcolor=lightblue]
45
+
46
+
start [shape=circle, fillcolor=green, label="Start"]
47
+
end [shape=doublecircle, fillcolor=red, label="End"]
48
+
49
+
start -> process1 [label="begin"]
50
+
process1 -> decision [label="check"]
51
+
decision -> process2 [label="yes"]
52
+
decision -> end [label="no"]
53
+
process2 -> end [label="done"]
54
+
}
55
+
]}
56
+
57
+
{2 Undirected Graph}
58
+
59
+
{@dot[
60
+
graph {
61
+
a -- b -- c
62
+
b -- d
63
+
c -- e
64
+
d -- e -- f
65
+
}
66
+
]}
67
+
68
+
{2 Subgraphs and Clusters}
69
+
70
+
{@dot[
71
+
digraph {
72
+
subgraph cluster_0 {
73
+
label="Process A"
74
+
style=filled
75
+
color=lightgrey
76
+
a0 -> a1 -> a2
77
+
}
78
+
79
+
subgraph cluster_1 {
80
+
label="Process B"
81
+
color=blue
82
+
b0 -> b1 -> b2
83
+
}
84
+
85
+
start -> a0
86
+
start -> b0
87
+
a2 -> end
88
+
b2 -> end
89
+
}
90
+
]}
91
+
92
+
{2 Record Shapes (Data Structures)}
93
+
94
+
{@dot[
95
+
digraph {
96
+
node [shape=record]
97
+
98
+
struct1 [label="<f0> left|<f1> mid|<f2> right"]
99
+
struct2 [label="<f0> one|<f1> two"]
100
+
struct3 [label="hello\nworld|{b|{c|<here> d|e}|f}|g|h"]
101
+
102
+
struct1:f1 -> struct2:f0
103
+
struct1:f2 -> struct3:here
104
+
}
105
+
]}
106
+
107
+
{2 Finite State Machine}
108
+
109
+
{@dot[
110
+
digraph FSM {
111
+
rankdir=LR
112
+
node [shape=circle]
113
+
114
+
start [shape=point]
115
+
q0 [label="q₀"]
116
+
q1 [label="q₁"]
117
+
q2 [label="q₂", shape=doublecircle]
118
+
119
+
start -> q0
120
+
q0 -> q0 [label="0"]
121
+
q0 -> q1 [label="1"]
122
+
q1 -> q0 [label="0"]
123
+
q1 -> q2 [label="1"]
124
+
q2 -> q2 [label="0,1"]
125
+
}
126
+
]}
127
+
128
+
{2 Binary Tree}
129
+
130
+
{@dot[
131
+
digraph Tree {
132
+
node [shape=circle]
133
+
134
+
8 -> 4
135
+
8 -> 12
136
+
4 -> 2
137
+
4 -> 6
138
+
12 -> 10
139
+
12 -> 14
140
+
}
141
+
]}
142
+
143
+
{1 Options}
144
+
145
+
The extension supports the following options:
146
+
147
+
- [layout] - Graphviz layout engine: [dot] (default), [neato], [fdp],
148
+
[sfdp], [circo], [twopi], [osage], [patchwork]
149
+
- [width] - CSS width (e.g., [500px], [100%])
150
+
- [height] - CSS height
151
+
- [format] - Output format: omit for client-side JS, or [png]/[svg] for
152
+
server-side rendering (requires [graphviz] CLI tools)
153
+
154
+
{2 Layout Example}
155
+
156
+
Different layout engines produce different arrangements:
157
+
158
+
{v
159
+
{@dot layout=circo[
160
+
digraph {
161
+
a -> b -> c -> d -> e -> a
162
+
}
163
+
]}
164
+
v}
165
+
166
+
{@dot layout=circo[
167
+
digraph {
168
+
a -> b -> c -> d -> e -> a
169
+
}
170
+
]}
171
+
172
+
{1 How It Works}
173
+
174
+
By default, diagrams are rendered client-side using the Viz.js library
175
+
(a WebAssembly port of Graphviz) loaded from a CDN. The extension injects
176
+
the necessary [<script>] tags into the HTML output.
177
+
178
+
For server-side rendering, install the [graphviz] package and use
179
+
[format=png] or [format=svg].
180
+
181
+
{1 DOT Syntax Reference}
182
+
183
+
DOT syntax basics:
184
+
- Directed graph: [digraph \{ ... \}]
185
+
- Undirected graph: [graph \{ ... \}]
186
+
- Edges: [A -> B] (directed) or [A -- B] (undirected)
187
+
- Node attributes: [A \[label="text", shape=box\]]
188
+
- Edge attributes: [A -> B \[label="edge", style=dashed\]]
189
+
190
+
See the {{:https://graphviz.org/doc/info/lang.html}DOT language documentation}
191
+
for the complete syntax reference.