Improve odoc extensions and align docsite HTML with stock odoc

odoc-docsite:
- Rename CSS classes to align with stock odoc conventions
- Use odoc-nav, odoc-content, odoc-tocs for compatibility
- Prefix docsite-specific features with docsite-* (header, sidebar, etc.)
- Add class="odoc" to body element

odoc extensions:
- Add blocks_of_nestable_elements to extension API for preserving refs
- Fix admonition extension to render cross-references properly
- Fix MSC extension resource handling for nested module pages
- Fix Mermaid extension dark mode styling

Documentation:
- Improve JMAP docs with diagrams, admonitions, and better organization
- Fix IMAP state diagram (remove confusing logout from NotAuthenticated)
- Add JMAP dependency on ocaml-imap for cross-package references

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Jon Ludlam 3 months ago f99ed5f4 a1988eb6

+55 -18

1 changed file

expand all

lib

imap

imap.mli

+55 -18

lib/imap/imap.mli

··· 8 8 A comprehensive IMAP client library implementing 9 9 {{:https://datatracker.ietf.org/doc/html/rfc9051}RFC 9051 IMAP4rev2}. 10 10 11 - {2 Protocol Flow} 11 + {2 Connection States} 12 + 13 + IMAP is a stateful protocol. The connection progresses through states, 14 + and operations are only valid in certain states: 15 + 16 + {@mermaid[ 17 + stateDiagram-v2 18 + [*] --> NotAuthenticated : connect 19 + NotAuthenticated --> Authenticated : login 20 + NotAuthenticated --> NotAuthenticated : starttls 21 + Authenticated --> Selected : select / examine 22 + Selected --> Selected : select / examine (different mailbox) 23 + Selected --> Authenticated : close / unselect 24 + Authenticated --> [*] : logout 25 + Selected --> [*] : logout 26 + ]} 27 + 28 + {b Not Authenticated}: Only {!Client.login}, {!Client.starttls}, and 29 + {!Client.capability} are available. 30 + 31 + {b Authenticated}: Mailbox operations like {!Client.list}, {!Client.create}, 32 + {!Client.status}. Must {!Client.select} a mailbox to access messages. 33 + 34 + {b Selected}: Message operations like {!Client.fetch}, {!Client.store}, 35 + {!Client.search}, {!Client.copy}. Call {!Client.close} to return to 36 + Authenticated state. 37 + 38 + {2 Message Addressing} 39 + 40 + Messages in a mailbox can be addressed two ways: 41 + 42 + - {b Sequence numbers} (1, 2, 3...): Position in mailbox. {e Changes when 43 + messages are deleted.} Use for "the first 10 messages". 44 + 45 + - {b UIDs} (unique identifiers): Permanent within a mailbox session. 46 + {e Never reused while UIDVALIDITY unchanged.} Use for "this specific 47 + message". 12 48 13 - A typical IMAP session follows this message sequence: 49 + {@mermaid[ 50 + flowchart LR 51 + subgraph Mailbox 52 + M1["Message seq=1, uid=105"] 53 + M2["Message seq=2, uid=108"] 54 + M3["Message seq=3, uid=112"] 55 + end 14 56 15 - {@msc[ 16 - msc { 17 - client, server; 57 + DELETE["delete seq=2"] 18 58 19 - server -> client [label="* OK IMAP4rev2 ready"]; 20 - client -> server [label="a001 LOGIN user pass"]; 21 - server -> client [label="a001 OK LOGIN completed"]; 22 - client -> server [label="a002 SELECT INBOX"]; 23 - server -> client [label="* 172 EXISTS"]; 24 - server -> client [label="a002 OK SELECT completed"]; 25 - client -> server [label="a003 FETCH 1:10 (ENVELOPE)"]; 26 - server -> client [label="* 1 FETCH (ENVELOPE ...)"]; 27 - server -> client [label="a003 OK FETCH completed"]; 28 - client -> server [label="a004 LOGOUT"]; 29 - server -> client [label="* BYE"]; 30 - server -> client [label="a004 OK LOGOUT completed"]; 31 - } 59 + subgraph After 60 + A1["Message seq=1, uid=105"] 61 + A2["Message seq=2, uid=112"] 62 + end 63 + 64 + Mailbox --> DELETE --> After 32 65 ]} 66 + 67 + Most {!Client} functions have two variants: [fetch] uses sequence numbers, 68 + [uid_fetch] uses UIDs. {b Prefer UID variants} when tracking specific 69 + messages across operations. 33 70 34 71 {2 Quick Start} 35 72

Configure Feed

Configure Feed