jon.recoil.org
A fork of mtelver's day10 project
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>
+98
odoc-admonition-extension/index.mld
+98
odoc-admonition-extension/index.mld
···
1
+
{0 Admonition Extension for odoc}
2
+
3
+
This extension adds support for admonition blocks (callouts) in odoc
4
+
documentation. Admonitions are used to highlight important information,
5
+
warnings, tips, and other notable content.
6
+
7
+
{1 Installation}
8
+
9
+
{[
10
+
opam install odoc-admonition-extension
11
+
]}
12
+
13
+
Once installed, the extension is automatically loaded by odoc.
14
+
15
+
{1 Usage}
16
+
17
+
Use the [@admonition] tag variants in documentation comments:
18
+
19
+
{v
20
+
(** Some documentation.
21
+
22
+
@admonition.note This is a note with important information.
23
+
*)
24
+
v}
25
+
26
+
{1 Examples}
27
+
28
+
{2 Note}
29
+
30
+
@admonition.note Notes are used for supplementary information that adds context or detail.
31
+
32
+
{2 Warning}
33
+
34
+
@admonition.warning Warnings alert readers to potential issues or things that could go wrong. Always validate user input before processing!
35
+
36
+
{2 Tip}
37
+
38
+
@admonition.tip Tips provide helpful suggestions or best practices. Use [Option.value ~default] instead of pattern matching when you just need a default value.
39
+
40
+
{2 Important}
41
+
42
+
@admonition.important Important blocks highlight critical information that readers should not miss.
43
+
44
+
{1 Admonition Kinds}
45
+
46
+
The extension supports the following tag variants:
47
+
48
+
{table
49
+
{tr
50
+
{th Tag}
51
+
{th Purpose}
52
+
}
53
+
{tr
54
+
{td [@admonition] or [@admonition.note]}
55
+
{td General supplementary information}
56
+
}
57
+
{tr
58
+
{td [@admonition.tip]}
59
+
{td Helpful suggestions and best practices}
60
+
}
61
+
{tr
62
+
{td [@admonition.warning]}
63
+
{td Potential issues or things that could go wrong}
64
+
}
65
+
{tr
66
+
{td [@admonition.important]}
67
+
{td Critical information that should not be missed}
68
+
}
69
+
}
70
+
71
+
{1 In API Documentation}
72
+
73
+
Admonitions are especially useful in module and function documentation:
74
+
75
+
{v
76
+
(** Connect to a database.
77
+
78
+
@admonition.warning This function will block until the connection
79
+
is established. Use {!connect_async} for non-blocking connections.
80
+
81
+
@admonition.tip For connection pooling, see {!Pool.create}.
82
+
*)
83
+
val connect : config -> t
84
+
v}
85
+
86
+
{1 Styling}
87
+
88
+
The extension generates HTML with appropriate CSS classes for styling.
89
+
Each admonition type has a distinct visual appearance with colors
90
+
that match its purpose:
91
+
92
+
- {b Note}: Blue, informational
93
+
- {b Tip}: Green, helpful
94
+
- {b Warning}: Orange, attention
95
+
- {b Important}: Red, critical
96
+
97
+
The CSS is automatically included when the extension is loaded and
98
+
supports both light and dark modes.
+191
odoc-dot-extension/index.mld
+191
odoc-dot-extension/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.
+141
odoc-mermaid-extension/index.mld
+141
odoc-mermaid-extension/index.mld
···
1
+
{0 Mermaid Extension for odoc}
2
+
3
+
This extension adds support for {{:https://mermaid.js.org/}Mermaid} diagrams
4
+
in odoc documentation. Mermaid is a JavaScript-based diagramming tool that
5
+
renders Markdown-inspired text definitions into diagrams.
6
+
7
+
{1 Installation}
8
+
9
+
{[
10
+
opam install odoc-mermaid-extension
11
+
]}
12
+
13
+
Once installed, the extension is automatically loaded by odoc.
14
+
15
+
{1 Usage}
16
+
17
+
Use the [{@mermaid[...]}] tag to embed Mermaid diagrams:
18
+
19
+
{v
20
+
{@mermaid[
21
+
graph LR
22
+
A[Start] --> B{Decision}
23
+
B -->|Yes| C[OK]
24
+
B -->|No| D[Cancel]
25
+
]}
26
+
v}
27
+
28
+
{1 Examples}
29
+
30
+
{2 Flowchart}
31
+
32
+
{@mermaid[
33
+
graph TD
34
+
A[Christmas] -->|Get money| B(Go shopping)
35
+
B --> C{Let me think}
36
+
C -->|One| D[Laptop]
37
+
C -->|Two| E[iPhone]
38
+
C -->|Three| F[Car]
39
+
]}
40
+
41
+
{2 Sequence Diagram}
42
+
43
+
{@mermaid[
44
+
sequenceDiagram
45
+
participant Alice
46
+
participant Bob
47
+
Alice->>John: Hello John, how are you?
48
+
loop Healthcheck
49
+
John->>John: Fight against hypochondria
50
+
end
51
+
Note right of John: Rational thoughts!
52
+
John-->>Alice: Great!
53
+
John->>Bob: How about you?
54
+
Bob-->>John: Jolly good!
55
+
]}
56
+
57
+
{2 State Diagram}
58
+
59
+
{@mermaid[
60
+
stateDiagram-v2
61
+
[*] --> Still
62
+
Still --> [*]
63
+
Still --> Moving
64
+
Moving --> Still
65
+
Moving --> Crash
66
+
Crash --> [*]
67
+
]}
68
+
69
+
{2 Class Diagram}
70
+
71
+
{@mermaid[
72
+
classDiagram
73
+
Animal <|-- Duck
74
+
Animal <|-- Fish
75
+
Animal <|-- Zebra
76
+
Animal : +int age
77
+
Animal : +String gender
78
+
Animal: +isMammal()
79
+
Animal: +mate()
80
+
class Duck{
81
+
+String beakColor
82
+
+swim()
83
+
+quack()
84
+
}
85
+
]}
86
+
87
+
{2 Entity Relationship Diagram}
88
+
89
+
{@mermaid[
90
+
erDiagram
91
+
CUSTOMER ||--o{ ORDER : places
92
+
ORDER ||--|{ LINE-ITEM : contains
93
+
CUSTOMER }|..|{ DELIVERY-ADDRESS : uses
94
+
]}
95
+
96
+
{2 Gantt Chart}
97
+
98
+
{@mermaid[
99
+
gantt
100
+
title A Gantt Diagram
101
+
dateFormat YYYY-MM-DD
102
+
section Section
103
+
A task :a1, 2024-01-01, 30d
104
+
Another task :after a1, 20d
105
+
section Another
106
+
Task in sec :2024-01-12, 12d
107
+
another task :24d
108
+
]}
109
+
110
+
{1 Options}
111
+
112
+
The extension supports the following options:
113
+
114
+
- [theme] - Mermaid theme: [default], [forest], [dark], [neutral]
115
+
- [width] - CSS width (e.g., [500px], [100%])
116
+
- [height] - CSS height
117
+
- [format] - Output format: omit for client-side JS, or [png]/[svg] for
118
+
server-side rendering (requires [mmdc] CLI tool)
119
+
120
+
{2 Theme Example}
121
+
122
+
{v
123
+
{@mermaid theme=forest[
124
+
graph LR
125
+
A --> B --> C
126
+
]}
127
+
v}
128
+
129
+
{@mermaid theme=forest[
130
+
graph LR
131
+
A --> B --> C
132
+
]}
133
+
134
+
{1 How It Works}
135
+
136
+
By default, diagrams are rendered client-side using the Mermaid JavaScript
137
+
library loaded from a CDN. The extension injects the necessary [<script>] tags
138
+
into the HTML output.
139
+
140
+
For server-side rendering (useful for PDF generation or environments without
141
+
JavaScript), install the [mmdc] CLI tool and use [format=png] or [format=svg].
+135
odoc-msc-extension/index.mld
+135
odoc-msc-extension/index.mld
···
1
+
{0 MSC Extension for odoc}
2
+
3
+
This extension adds support for {{:https://www.mcternan.me.uk/mscgen/}Message
4
+
Sequence Charts} (MSC) in odoc documentation. MSC is a graphical and textual
5
+
language for describing interactions between components.
6
+
7
+
{1 Installation}
8
+
9
+
{[
10
+
opam install odoc-msc-extension
11
+
]}
12
+
13
+
Once installed, the extension is automatically loaded by odoc.
14
+
15
+
{1 Usage}
16
+
17
+
Use the [{@msc[...]}] tag to embed Message Sequence Charts:
18
+
19
+
{v
20
+
{@msc[
21
+
msc {
22
+
a, b, c;
23
+
a -> b [label="request"];
24
+
b -> c [label="forward"];
25
+
c -> b [label="response"];
26
+
b -> a [label="reply"];
27
+
}
28
+
]}
29
+
v}
30
+
31
+
{1 Examples}
32
+
33
+
{2 Simple Request-Response}
34
+
35
+
{@msc[
36
+
msc {
37
+
client, server;
38
+
client -> server [label="GET /api/data"];
39
+
server -> client [label="200 OK"];
40
+
}
41
+
]}
42
+
43
+
{2 Three-Party Interaction}
44
+
45
+
{@msc[
46
+
msc {
47
+
user, frontend, backend, database;
48
+
49
+
user -> frontend [label="click button"];
50
+
frontend -> backend [label="POST /submit"];
51
+
backend -> database [label="INSERT"];
52
+
database -> backend [label="OK"];
53
+
backend -> frontend [label="201 Created"];
54
+
frontend -> user [label="show success"];
55
+
}
56
+
]}
57
+
58
+
{2 With Conditions and Boxes}
59
+
60
+
{@msc[
61
+
msc {
62
+
a, b, c;
63
+
64
+
a box a [label="prepare"];
65
+
a -> b [label="request"];
66
+
b -> c [label="check"];
67
+
c -> b [label="valid"];
68
+
b box b [label="process"];
69
+
b -> a [label="done"];
70
+
}
71
+
]}
72
+
73
+
{2 Parallel Messages}
74
+
75
+
{@msc[
76
+
msc {
77
+
client, cache, origin;
78
+
79
+
client -> cache [label="GET /resource"];
80
+
--- [label="cache miss"];
81
+
cache -> origin [label="fetch"];
82
+
origin -> cache [label="content"];
83
+
cache -> client [label="200 OK"];
84
+
}
85
+
]}
86
+
87
+
{2 Authentication Flow}
88
+
89
+
{@msc[
90
+
msc {
91
+
browser, app, auth, api;
92
+
93
+
browser -> app [label="access protected"];
94
+
app -> auth [label="redirect to login"];
95
+
auth -> browser [label="login form"];
96
+
browser -> auth [label="credentials"];
97
+
auth -> app [label="auth code"];
98
+
app -> auth [label="exchange code"];
99
+
auth -> app [label="access token"];
100
+
app -> api [label="request + token"];
101
+
api -> app [label="data"];
102
+
app -> browser [label="render page"];
103
+
}
104
+
]}
105
+
106
+
{1 Options}
107
+
108
+
The extension supports the following options:
109
+
110
+
- [named-style] - MscGen style: [basic], [lazy], [classic], etc.
111
+
- [width] - CSS width (e.g., [500px], [100%])
112
+
- [height] - CSS height
113
+
- [format] - Output format: omit for client-side JS, or [png]/[svg] for
114
+
server-side rendering (requires [mscgen] CLI tool)
115
+
116
+
{1 How It Works}
117
+
118
+
By default, diagrams are rendered client-side using the mscgen_js library
119
+
loaded from a CDN. The extension injects the necessary [<script>] tags
120
+
into the HTML output.
121
+
122
+
For server-side rendering, install the [mscgen] CLI tool and use
123
+
[format=png] or [format=svg].
124
+
125
+
{1 Syntax Reference}
126
+
127
+
MSC syntax basics:
128
+
- Declare entities: [a, b, c;]
129
+
- Messages: [a -> b \[label="text"\];]
130
+
- Return messages: [a <- b \[label="text"\];]
131
+
- Boxes: [a box a \[label="text"\];]
132
+
- Separators: [--- \[label="text"\];]
133
+
134
+
See the {{:https://www.mcternan.me.uk/mscgen/}MscGen documentation} for
135
+
the complete syntax reference.
+119
odoc-rfc-extension/index.mld
+119
odoc-rfc-extension/index.mld
···
1
+
{0 RFC Extension for odoc}
2
+
3
+
This extension adds support for citing IETF RFCs (Request for Comments) in
4
+
odoc documentation. It provides a convenient way to reference internet
5
+
standards with automatic linking and formatting.
6
+
7
+
{1 Installation}
8
+
9
+
{[
10
+
opam install odoc-rfc-extension
11
+
]}
12
+
13
+
Once installed, the extension is automatically loaded by odoc.
14
+
15
+
{1 Usage}
16
+
17
+
Use the [@rfc] tag to cite an RFC:
18
+
19
+
{v
20
+
(** See @rfc 5321 for SMTP details. *)
21
+
v}
22
+
23
+
This creates a formatted citation with a link to the official RFC document.
24
+
25
+
{1 Examples}
26
+
27
+
{2 IMAP4rev2}
28
+
29
+
@rfc 9051
30
+
31
+
{2 SMTP}
32
+
33
+
@rfc 5321
34
+
35
+
{2 HTTP/1.1 (original, now obsoleted)}
36
+
37
+
@rfc 2616
38
+
39
+
{2 Core Internet Standards}
40
+
41
+
Internet Protocol (IP):
42
+
43
+
@rfc 791
44
+
45
+
Transmission Control Protocol (TCP):
46
+
47
+
@rfc 793
48
+
49
+
User Datagram Protocol (UDP):
50
+
51
+
@rfc 768
52
+
53
+
Domain Name System (DNS):
54
+
55
+
@rfc 1035
56
+
57
+
{2 Modern Web Standards}
58
+
59
+
HTTP Semantics:
60
+
61
+
@rfc 9110
62
+
63
+
HTTP Caching:
64
+
65
+
@rfc 9111
66
+
67
+
JSON Web Token (JWT):
68
+
69
+
@rfc 7519
70
+
71
+
OAuth 2.0:
72
+
73
+
@rfc 6749
74
+
75
+
{2 Email Standards}
76
+
77
+
Internet Message Format:
78
+
79
+
@rfc 5322
80
+
81
+
IMAP IDLE:
82
+
83
+
@rfc 2177
84
+
85
+
IMAP CONDSTORE:
86
+
87
+
@rfc 7162
88
+
89
+
{2 Security Standards}
90
+
91
+
TLS 1.2:
92
+
93
+
@rfc 5246
94
+
95
+
TLS 1.3:
96
+
97
+
@rfc 8446
98
+
99
+
{1 In API Documentation}
100
+
101
+
RFC citations are especially useful in API documentation:
102
+
103
+
{v
104
+
(** Parse an email address according to @rfc 5322.
105
+
106
+
@raises Parse_error if the address is malformed *)
107
+
val parse : string -> t
108
+
v}
109
+
110
+
{1 How It Works}
111
+
112
+
The extension generates links to the official IETF datatracker:
113
+
114
+
{v
115
+
https://datatracker.ietf.org/doc/html/rfc<number>
116
+
v}
117
+
118
+
The citation is styled with a distinctive appearance to make RFC references
119
+
easy to identify in documentation.