An RFC 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>
+121
+119
index.mld
+119
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.