-28

dune-project

reviewed

··· 42 42 (package (name odoc-bench)) 43 43 (package (name sherlodoc)) 44 44 45 45 - ; Example extension packages 46 46 - (package 47 47 - (name odoc-dot-extension) 48 48 - (synopsis "Graphviz/DOT diagram support for odoc documentation") 49 49 - (description "Renders {@dot[...]} code blocks as SVG diagrams using Graphviz. 50 50 - Supports width, height, and layout engine options.") 51 51 - (depends 52 52 - (ocaml (>= 4.14)) 53 53 - odoc)) 54 54 - 55 55 - (package 56 56 - (name odoc-mermaid-extension) 57 57 - (synopsis "Mermaid diagram support for odoc documentation") 58 58 - (description "Renders {@mermaid[...]} code blocks as interactive diagrams. 59 59 - Supports flowcharts, sequence diagrams, class diagrams, and more.") 60 60 - (depends 61 61 - (ocaml (>= 4.14)) 62 62 - odoc)) 63 63 - 64 64 - (package 65 65 - (name odoc-msc-extension) 66 66 - (synopsis "Message Sequence Chart support for odoc documentation") 67 67 - (description "Renders {@msc[...]} code blocks as message sequence charts. 68 68 - Uses the MscGen syntax for defining sequence diagrams.") 69 69 - (depends 70 70 - (ocaml (>= 4.14)) 71 71 - odoc)) 72 72 - 73 45 (using mdx 0.3) 74 46 75 47 ; Sherlodoc

-292

examples/extensions/dot/src/dot_extension.ml

reviewed

··· 1 1 - (** Graphviz/DOT diagram extension for odoc. 2 2 - 3 3 - Renders [{@dot[...]}] code blocks as diagrams. By default uses client-side 4 4 - JavaScript (Viz.js), but can render server-side to PNG/SVG with format option. 5 5 - 6 6 - Example: 7 7 - {[ 8 8 - {@dot layout=neato[ 9 9 - digraph G { 10 10 - a -> b -> c; 11 11 - b -> d; 12 12 - } 13 13 - ]} 14 14 - ]} 15 15 - *) 16 16 - 17 17 - module Api = Odoc_extension_api 18 18 - module Block = Odoc_document.Types.Block 19 19 - module Inline = Odoc_document.Types.Inline 20 20 - 21 21 - (** The Viz.js library URL for client-side rendering *) 22 22 - let viz_js_url = "https://unpkg.com/viz.js@2.1.2/viz.js" 23 23 - let viz_full_js_url = "https://unpkg.com/viz.js@2.1.2/full.render.js" 24 24 - 25 25 - (** Generate a unique ID for each diagram *) 26 26 - let diagram_counter = ref 0 27 27 - 28 28 - let fresh_id () = 29 29 - incr diagram_counter; 30 30 - Printf.sprintf "dot-diagram-%d" !diagram_counter 31 31 - 32 32 - (** Extract option values *) 33 33 - let get_layout tags = 34 34 - Api.get_binding "layout" tags 35 35 - |> Option.value ~default:"dot" 36 36 - 37 37 - let get_format tags = 38 38 - Api.get_binding "format" tags 39 39 - 40 40 - let get_filename tags = 41 41 - Api.get_binding "filename" tags 42 42 - 43 43 - let get_dimensions tags = 44 44 - let width = Api.get_binding "width" tags in 45 45 - let height = Api.get_binding "height" tags in 46 46 - (width, height) 47 47 - 48 48 - (** Check if content looks like a complete DOT graph *) 49 49 - let has_graph_wrapper content = 50 50 - let trimmed = String.trim content in 51 51 - String.length trimmed > 0 && 52 52 - (let starts_with prefix s = 53 53 - String.length s >= String.length prefix && 54 54 - String.sub s 0 (String.length prefix) = prefix 55 55 - in 56 56 - starts_with "digraph" trimmed || 57 57 - starts_with "graph" trimmed || 58 58 - starts_with "strict" trimmed) 59 59 - 60 60 - (** Wrap content in a digraph if needed *) 61 61 - let ensure_graph_wrapper content = 62 62 - if has_graph_wrapper content then content 63 63 - else Printf.sprintf "digraph G {\n%s\n}" content 64 64 - 65 65 - (** Build inline style string from dimensions *) 66 66 - let make_style width height = 67 67 - let parts = [] in 68 68 - let parts = match width with 69 69 - | Some w -> Printf.sprintf "width: %s" w :: parts 70 70 - | None -> parts 71 71 - in 72 72 - let parts = match height with 73 73 - | Some h -> Printf.sprintf "height: %s" h :: parts 74 74 - | None -> parts 75 75 - in 76 76 - match parts with 77 77 - | [] -> "" 78 78 - | ps -> String.concat "; " (List.rev ps) 79 79 - 80 80 - (** Run the dot command to render to a specific format *) 81 81 - let run_dot ~layout ~format content = 82 82 - (* Create temp file for input *) 83 83 - let tmp_in = Filename.temp_file "odoc_dot_" ".dot" in 84 84 - let tmp_out = Filename.temp_file "odoc_dot_" ("." ^ format) in 85 85 - Fun.protect ~finally:(fun () -> 86 86 - (try Sys.remove tmp_in with _ -> ()); 87 87 - (try Sys.remove tmp_out with _ -> ()) 88 88 - ) (fun () -> 89 89 - (* Write DOT content *) 90 90 - let oc = open_out tmp_in in 91 91 - output_string oc content; 92 92 - close_out oc; 93 93 - (* Run dot command *) 94 94 - let cmd = Printf.sprintf "dot -K%s -T%s -o %s %s 2>&1" 95 95 - layout format (Filename.quote tmp_out) (Filename.quote tmp_in) in 96 96 - let ic = Unix.open_process_in cmd in 97 97 - let error_output = Buffer.create 256 in 98 98 - (try 99 99 - while true do 100 100 - Buffer.add_string error_output (input_line ic); 101 101 - Buffer.add_char error_output '\n' 102 102 - done 103 103 - with End_of_file -> ()); 104 104 - let status = Unix.close_process_in ic in 105 105 - match status with 106 106 - | Unix.WEXITED 0 -> 107 107 - (* Read the output file *) 108 108 - let ic = open_in_bin tmp_out in 109 109 - let len = in_channel_length ic in 110 110 - let data = Bytes.create len in 111 111 - really_input ic data 0 len; 112 112 - close_in ic; 113 113 - Ok data 114 114 - | _ -> 115 115 - Error (Buffer.contents error_output) 116 116 - ) 117 117 - 118 118 - (** JavaScript code to render a single diagram (for client-side rendering) *) 119 119 - let render_script id layout content = 120 120 - Printf.sprintf {| 121 121 - (function() { 122 122 - function renderDot() { 123 123 - var container = document.getElementById('%s'); 124 124 - if (!container) return; 125 125 - 126 126 - if (typeof Viz === 'undefined') { 127 127 - container.innerHTML = '<pre style="color: red;">Viz.js not loaded</pre>'; 128 128 - return; 129 129 - } 130 130 - 131 131 - var viz = new Viz(); 132 132 - viz.renderSVGElement(%S, { engine: %S }) 133 133 - .then(function(svg) { 134 134 - container.innerHTML = ''; 135 135 - container.appendChild(svg); 136 136 - }) 137 137 - .catch(function(error) { 138 138 - container.innerHTML = '<pre style="color: red;">' + error + '</pre>'; 139 139 - }); 140 140 - } 141 141 - 142 142 - if (document.readyState === 'loading') { 143 143 - document.addEventListener('DOMContentLoaded', renderDot); 144 144 - } else { 145 145 - renderDot(); 146 146 - } 147 147 - })(); 148 148 - |} id content layout 149 149 - 150 150 - module Dot_handler : Api.Code_Block_Extension = struct 151 151 - let prefix = "dot" 152 152 - 153 153 - let to_document meta content = 154 154 - let id = fresh_id () in 155 155 - let layout = get_layout meta.Api.tags in 156 156 - let format = get_format meta.Api.tags in 157 157 - let filename_opt = get_filename meta.Api.tags in 158 158 - let (width, height) = get_dimensions meta.Api.tags in 159 159 - let style = make_style width height in 160 160 - let style_attr = if style = "" then "" else Printf.sprintf " style=\"%s\"" style in 161 161 - 162 162 - (* Auto-wrap in digraph if needed *) 163 163 - let dot_content = ensure_graph_wrapper content in 164 164 - 165 165 - match format with 166 166 - | Some "png" | Some "svg" -> 167 167 - (* Server-side rendering *) 168 168 - let fmt = match format with Some f -> f | None -> "png" in 169 169 - let base_filename = match filename_opt with 170 170 - | Some f -> f 171 171 - | None -> Printf.sprintf "dot-%s.%s" id fmt 172 172 - in 173 173 - (match run_dot ~layout ~format:fmt dot_content with 174 174 - | Ok data -> 175 175 - let html = Printf.sprintf 176 176 - {|<div id="%s" class="odoc-dot-diagram"%s><img src="%s" alt="DOT diagram" /></div>|} 177 177 - id style_attr base_filename 178 178 - in 179 179 - let block = Block.[{ 180 180 - attr = ["odoc-dot"]; 181 181 - desc = Raw_markup ("html", html) 182 182 - }] in 183 183 - Some { 184 184 - Api.content = block; 185 185 - overrides = []; 186 186 - resources = []; 187 187 - assets = [{ Api.asset_filename = base_filename; asset_content = data }]; 188 188 - } 189 189 - | Error err -> 190 190 - (* Show error message *) 191 191 - let html = Printf.sprintf 192 192 - "<div id=\"%s\" class=\"odoc-dot-diagram odoc-dot-error\"><pre style=\"color: red;\">Error rendering DOT diagram (is graphviz installed?):\n%s</pre><pre>%s</pre></div>" 193 193 - id err content 194 194 - in 195 195 - let block = Block.[{ 196 196 - attr = ["odoc-dot"; "odoc-dot-error"]; 197 197 - desc = Raw_markup ("html", html) 198 198 - }] in 199 199 - Some { 200 200 - Api.content = block; 201 201 - overrides = []; 202 202 - resources = []; 203 203 - assets = []; 204 204 - }) 205 205 - 206 206 - | Some unknown_format -> 207 207 - (* Unknown format - show error *) 208 208 - let html = Printf.sprintf 209 209 - {|<div class="odoc-dot-error"><pre style="color: red;">Unknown format: %s (supported: png, svg)</pre></div>|} 210 210 - unknown_format 211 211 - in 212 212 - let block = Block.[{ 213 213 - attr = ["odoc-dot-error"]; 214 214 - desc = Raw_markup ("html", html) 215 215 - }] in 216 216 - Some { 217 217 - Api.content = block; 218 218 - overrides = []; 219 219 - resources = []; 220 220 - assets = []; 221 221 - } 222 222 - 223 223 - | None -> 224 224 - (* Default: client-side JavaScript rendering *) 225 225 - let html = Printf.sprintf 226 226 - {|<div id="%s" class="odoc-dot-diagram"%s><pre>%s</pre></div>|} 227 227 - id style_attr content 228 228 - in 229 229 - let script = render_script id layout dot_content in 230 230 - let block = Block.[{ 231 231 - attr = ["odoc-dot"]; 232 232 - desc = Raw_markup ("html", html) 233 233 - }] in 234 234 - Some { 235 235 - Api.content = block; 236 236 - overrides = []; 237 237 - resources = [ 238 238 - Api.Js_url viz_js_url; 239 239 - Api.Js_url viz_full_js_url; 240 240 - Api.Js_inline script; 241 241 - ]; 242 242 - assets = []; 243 243 - } 244 244 - end 245 245 - 246 246 - (** CSS for dot diagrams *) 247 247 - let dot_css = {| 248 248 - .odoc-dot-diagram { 249 249 - margin: 1em 0; 250 250 - overflow: auto; 251 251 - } 252 252 - 253 253 - .odoc-dot-diagram svg, 254 254 - .odoc-dot-diagram img { 255 255 - max-width: 100%; 256 256 - height: auto; 257 257 - } 258 258 - 259 259 - .odoc-dot-diagram pre { 260 260 - background: #f5f5f5; 261 261 - padding: 1em; 262 262 - border-radius: 4px; 263 263 - overflow-x: auto; 264 264 - } 265 265 - 266 266 - .odoc-dot-error pre { 267 267 - color: #c00; 268 268 - } 269 269 - |} 270 270 - 271 271 - (** Extension documentation *) 272 272 - let extension_info : Api.extension_info = { 273 273 - info_kind = `Code_block; 274 274 - info_prefix = "dot"; 275 275 - info_description = "Render Graphviz/DOT diagrams. Uses client-side Viz.js by default, or server-side graphviz with format=png|svg."; 276 276 - info_options = [ 277 277 - { opt_name = "format"; opt_description = "Output format: png, svg (server-side), or omit for client-side JS"; opt_default = None }; 278 278 - { opt_name = "layout"; opt_description = "Graphviz layout engine"; opt_default = Some "dot" }; 279 279 - { opt_name = "width"; opt_description = "CSS width (e.g., 500px, 100%)"; opt_default = None }; 280 280 - { opt_name = "height"; opt_description = "CSS height"; opt_default = None }; 281 281 - { opt_name = "filename"; opt_description = "Output filename for server-side rendering"; opt_default = Some "auto-generated" }; 282 282 - ]; 283 283 - info_example = Some "{@dot format=png layout=neato[a -> b -> c]}"; 284 284 - } 285 285 - 286 286 - let () = 287 287 - Api.Registry.register_code_block (module Dot_handler); 288 288 - Api.Registry.register_extension_info extension_info; 289 289 - Api.Registry.register_support_file ~prefix:"dot" { 290 290 - filename = "extensions/dot.css"; 291 291 - content = dot_css; 292 292 - }

-10

examples/extensions/dot/src/dune

reviewed

··· 1 1 - (library 2 2 - (name dot_extension) 3 3 - (public_name odoc-dot-extension.impl) 4 4 - (libraries odoc_extension_api odoc_parser unix)) 5 5 - 6 6 - (plugin 7 7 - (name odoc-dot-extension) 8 8 - (package odoc-dot-extension) 9 9 - (libraries odoc-dot-extension.impl) 10 10 - (site (odoc extensions)))

-10

examples/extensions/mermaid/src/dune

reviewed

··· 1 1 - (library 2 2 - (name mermaid_extension) 3 3 - (public_name odoc-mermaid-extension.impl) 4 4 - (libraries odoc_extension_api odoc_parser unix)) 5 5 - 6 6 - (plugin 7 7 - (name odoc-mermaid-extension) 8 8 - (package odoc-mermaid-extension) 9 9 - (libraries odoc-mermaid-extension.impl) 10 10 - (site (odoc extensions)))

-266

examples/extensions/mermaid/src/mermaid_extension.ml

reviewed

··· 1 1 - (** Mermaid diagram extension for odoc. 2 2 - 3 3 - Renders [{@mermaid[...]}] code blocks as diagrams. By default uses client-side 4 4 - JavaScript, but can render server-side to PNG/SVG with format option 5 5 - (requires mermaid-cli/mmdc). 6 6 - 7 7 - Example: 8 8 - {[ 9 9 - {@mermaid theme=forest[ 10 10 - graph LR 11 11 - A[Start] --> B{Decision} 12 12 - B -->|Yes| C[OK] 13 13 - B -->|No| D[Cancel] 14 14 - ]} 15 15 - ]} 16 16 - *) 17 17 - 18 18 - module Api = Odoc_extension_api 19 19 - module Block = Odoc_document.Types.Block 20 20 - module Inline = Odoc_document.Types.Inline 21 21 - 22 22 - (** Mermaid.js CDN URL *) 23 23 - let mermaid_js_url = "https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.min.js" 24 24 - 25 25 - (** Generate a unique ID for each diagram *) 26 26 - let diagram_counter = ref 0 27 27 - 28 28 - let fresh_id () = 29 29 - incr diagram_counter; 30 30 - Printf.sprintf "mermaid-diagram-%d" !diagram_counter 31 31 - 32 32 - (** Extract option values *) 33 33 - let get_theme tags = 34 34 - Api.get_binding "theme" tags 35 35 - |> Option.value ~default:"default" 36 36 - 37 37 - let get_format tags = 38 38 - Api.get_binding "format" tags 39 39 - 40 40 - let get_filename tags = 41 41 - Api.get_binding "filename" tags 42 42 - 43 43 - let get_dimensions tags = 44 44 - let width = Api.get_binding "width" tags in 45 45 - let height = Api.get_binding "height" tags in 46 46 - (width, height) 47 47 - 48 48 - (** Build inline style string from dimensions *) 49 49 - let make_style width height = 50 50 - let parts = [] in 51 51 - let parts = match width with 52 52 - | Some w -> Printf.sprintf "width: %s" w :: parts 53 53 - | None -> parts 54 54 - in 55 55 - let parts = match height with 56 56 - | Some h -> Printf.sprintf "height: %s" h :: parts 57 57 - | None -> parts 58 58 - in 59 59 - match parts with 60 60 - | [] -> "" 61 61 - | ps -> String.concat "; " (List.rev ps) 62 62 - 63 63 - (** HTML-escape content for safe embedding *) 64 64 - let html_escape s = 65 65 - let buf = Buffer.create (String.length s) in 66 66 - String.iter (fun c -> 67 67 - match c with 68 68 - | '<' -> Buffer.add_string buf "&lt;" 69 69 - | '>' -> Buffer.add_string buf "&gt;" 70 70 - | '&' -> Buffer.add_string buf "&amp;" 71 71 - | '"' -> Buffer.add_string buf "&quot;" 72 72 - | c -> Buffer.add_char buf c 73 73 - ) s; 74 74 - Buffer.contents buf 75 75 - 76 76 - (** Puppeteer config for environments that need --no-sandbox *) 77 77 - let puppeteer_config = {|{"args": ["--no-sandbox", "--disable-setuid-sandbox"]}|} 78 78 - 79 79 - (** Run mmdc (mermaid-cli) to render to a specific format *) 80 80 - let run_mmdc ~theme ~format content = 81 81 - let tmp_in = Filename.temp_file "odoc_mermaid_" ".mmd" in 82 82 - let tmp_out = Filename.temp_file "odoc_mermaid_" ("." ^ format) in 83 83 - let tmp_config = Filename.temp_file "odoc_mermaid_" ".json" in 84 84 - Fun.protect ~finally:(fun () -> 85 85 - (try Sys.remove tmp_in with _ -> ()); 86 86 - (try Sys.remove tmp_out with _ -> ()); 87 87 - (try Sys.remove tmp_config with _ -> ()) 88 88 - ) (fun () -> 89 89 - (* Write Mermaid content *) 90 90 - let oc = open_out tmp_in in 91 91 - output_string oc content; 92 92 - close_out oc; 93 93 - (* Write puppeteer config for --no-sandbox *) 94 94 - let oc = open_out tmp_config in 95 95 - output_string oc puppeteer_config; 96 96 - close_out oc; 97 97 - (* Run mmdc command with puppeteer config *) 98 98 - let cmd = Printf.sprintf "mmdc -i %s -o %s -t %s -b transparent -p %s 2>&1" 99 99 - (Filename.quote tmp_in) (Filename.quote tmp_out) theme (Filename.quote tmp_config) in 100 100 - let ic = Unix.open_process_in cmd in 101 101 - let error_output = Buffer.create 256 in 102 102 - (try 103 103 - while true do 104 104 - Buffer.add_string error_output (input_line ic); 105 105 - Buffer.add_char error_output '\n' 106 106 - done 107 107 - with End_of_file -> ()); 108 108 - let status = Unix.close_process_in ic in 109 109 - match status with 110 110 - | Unix.WEXITED 0 -> 111 111 - (* Read the output file *) 112 112 - let ic = open_in_bin tmp_out in 113 113 - let len = in_channel_length ic in 114 114 - let data = Bytes.create len in 115 115 - really_input ic data 0 len; 116 116 - close_in ic; 117 117 - Ok data 118 118 - | _ -> 119 119 - Error (Buffer.contents error_output) 120 120 - ) 121 121 - 122 122 - module Mermaid_handler : Api.Code_Block_Extension = struct 123 123 - let prefix = "mermaid" 124 124 - 125 125 - let to_document meta content = 126 126 - let id = fresh_id () in 127 127 - let theme = get_theme meta.Api.tags in 128 128 - let format = get_format meta.Api.tags in 129 129 - let filename_opt = get_filename meta.Api.tags in 130 130 - let (width, height) = get_dimensions meta.Api.tags in 131 131 - let style = make_style width height in 132 132 - let style_attr = if style = "" then "" else Printf.sprintf " style=\"%s\"" style in 133 133 - 134 134 - match format with 135 135 - | Some "png" | Some "svg" -> 136 136 - (* Server-side rendering with mmdc *) 137 137 - let fmt = match format with Some f -> f | None -> "png" in 138 138 - let base_filename = match filename_opt with 139 139 - | Some f -> f 140 140 - | None -> Printf.sprintf "mermaid-%s.%s" id fmt 141 141 - in 142 142 - (match run_mmdc ~theme ~format:fmt content with 143 143 - | Ok data -> 144 144 - let html = Printf.sprintf 145 145 - {|<div id="%s" class="odoc-mermaid-diagram"%s><img src="%s" alt="Mermaid diagram" /></div>|} 146 146 - id style_attr base_filename 147 147 - in 148 148 - let block = Block.[{ 149 149 - attr = ["odoc-mermaid"]; 150 150 - desc = Raw_markup ("html", html) 151 151 - }] in 152 152 - Some { 153 153 - Api.content = block; 154 154 - overrides = []; 155 155 - resources = []; 156 156 - assets = [{ Api.asset_filename = base_filename; asset_content = data }]; 157 157 - } 158 158 - | Error err -> 159 159 - (* Show error message *) 160 160 - let html = Printf.sprintf 161 161 - "<div id=\"%s\" class=\"odoc-mermaid-diagram odoc-mermaid-error\"><pre style=\"color: red;\">Error rendering Mermaid diagram (is mmdc installed?):\n%s</pre><pre>%s</pre></div>" 162 162 - id err (html_escape content) 163 163 - in 164 164 - let block = Block.[{ 165 165 - attr = ["odoc-mermaid"; "odoc-mermaid-error"]; 166 166 - desc = Raw_markup ("html", html) 167 167 - }] in 168 168 - Some { 169 169 - Api.content = block; 170 170 - overrides = []; 171 171 - resources = []; 172 172 - assets = []; 173 173 - }) 174 174 - 175 175 - | Some unknown_format -> 176 176 - let html = Printf.sprintf 177 177 - {|<div class="odoc-mermaid-error"><pre style="color: red;">Unknown format: %s (supported: png, svg)</pre></div>|} 178 178 - unknown_format 179 179 - in 180 180 - let block = Block.[{ 181 181 - attr = ["odoc-mermaid-error"]; 182 182 - desc = Raw_markup ("html", html) 183 183 - }] in 184 184 - Some { 185 185 - Api.content = block; 186 186 - overrides = []; 187 187 - resources = []; 188 188 - assets = []; 189 189 - } 190 190 - 191 191 - | None -> 192 192 - (* Default: client-side JavaScript rendering *) 193 193 - let html = Printf.sprintf 194 194 - {|<div id="%s" class="odoc-mermaid-diagram"%s><pre class="mermaid">%s</pre></div>|} 195 195 - id style_attr (html_escape content) 196 196 - in 197 197 - let init_script = Printf.sprintf {| 198 198 - if (typeof window.mermaidInitialized === 'undefined') { 199 199 - window.mermaidInitialized = true; 200 200 - mermaid.initialize({ 201 201 - startOnLoad: true, 202 202 - theme: '%s', 203 203 - securityLevel: 'loose' 204 204 - }); 205 205 - } 206 206 - |} theme 207 207 - in 208 208 - let block = Block.[{ 209 209 - attr = ["odoc-mermaid"]; 210 210 - desc = Raw_markup ("html", html) 211 211 - }] in 212 212 - Some { 213 213 - Api.content = block; 214 214 - overrides = []; 215 215 - resources = [ 216 216 - Api.Js_url mermaid_js_url; 217 217 - Api.Js_inline init_script; 218 218 - ]; 219 219 - assets = []; 220 220 - } 221 221 - end 222 222 - 223 223 - (** CSS for mermaid diagrams *) 224 224 - let mermaid_css = {| 225 225 - .odoc-mermaid-diagram { 226 226 - margin: 1em 0; 227 227 - overflow: auto; 228 228 - } 229 229 - 230 230 - .odoc-mermaid-diagram svg, 231 231 - .odoc-mermaid-diagram img { 232 232 - max-width: 100%; 233 233 - height: auto; 234 234 - } 235 235 - 236 236 - .odoc-mermaid-diagram pre.mermaid { 237 237 - background: transparent; 238 238 - } 239 239 - 240 240 - .odoc-mermaid-error pre { 241 241 - color: #c00; 242 242 - } 243 243 - |} 244 244 - 245 245 - (** Extension documentation *) 246 246 - let extension_info : Api.extension_info = { 247 247 - info_kind = `Code_block; 248 248 - info_prefix = "mermaid"; 249 249 - info_description = "Render Mermaid diagrams (flowcharts, sequence diagrams, etc.). Uses client-side JS by default, or server-side mmdc with format=png|svg."; 250 250 - info_options = [ 251 251 - { opt_name = "format"; opt_description = "Output format: png, svg (requires mmdc), or omit for client-side JS"; opt_default = None }; 252 252 - { opt_name = "theme"; opt_description = "Mermaid theme (default, forest, dark, neutral)"; opt_default = Some "default" }; 253 253 - { opt_name = "width"; opt_description = "CSS width (e.g., 500px, 100%)"; opt_default = None }; 254 254 - { opt_name = "height"; opt_description = "CSS height"; opt_default = None }; 255 255 - { opt_name = "filename"; opt_description = "Output filename for server-side rendering"; opt_default = Some "auto-generated" }; 256 256 - ]; 257 257 - info_example = Some "{@mermaid format=png theme=forest[graph LR; A-->B]}"; 258 258 - } 259 259 - 260 260 - let () = 261 261 - Api.Registry.register_code_block (module Mermaid_handler); 262 262 - Api.Registry.register_extension_info extension_info; 263 263 - Api.Registry.register_support_file ~prefix:"mermaid" { 264 264 - filename = "extensions/mermaid.css"; 265 265 - content = mermaid_css; 266 266 - }

-10

examples/extensions/msc/src/dune

reviewed

··· 1 1 - (library 2 2 - (name msc_extension) 3 3 - (public_name odoc-msc-extension.impl) 4 4 - (libraries odoc_extension_api odoc_parser unix)) 5 5 - 6 6 - (plugin 7 7 - (name odoc-msc-extension) 8 8 - (package odoc-msc-extension) 9 9 - (libraries odoc-msc-extension.impl) 10 10 - (site (odoc extensions)))

-272

examples/extensions/msc/src/msc_extension.ml

reviewed

··· 1 1 - (** Message Sequence Chart extension for odoc. 2 2 - 3 3 - Renders [{@msc[...]}] code blocks as sequence diagrams. By default uses 4 4 - client-side JavaScript (mscgen-inpage), but can render server-side to 5 5 - PNG/SVG with format option (requires mscgen). 6 6 - 7 7 - Example: 8 8 - {[ 9 9 - {@msc format=png width=600px[ 10 10 - msc { 11 11 - a, b, c; 12 12 - a -> b [label="request"]; 13 13 - b -> c [label="forward"]; 14 14 - c -> b [label="response"]; 15 15 - b -> a [label="reply"]; 16 16 - } 17 17 - ]} 18 18 - ]} 19 19 - *) 20 20 - 21 21 - module Api = Odoc_extension_api 22 22 - module Block = Odoc_document.Types.Block 23 23 - module Inline = Odoc_document.Types.Inline 24 24 - 25 25 - (** MscGen.js CDN URL - the inpage version auto-renders on DOMContentLoaded *) 26 26 - let mscgen_js_url = "https://unpkg.com/mscgenjs-inpage@4/dist/mscgen-inpage.js" 27 27 - 28 28 - (** Script to load mscgenjs with defer-like behavior *) 29 29 - let loader_script = Printf.sprintf {| 30 30 - (function() { 31 31 - function loadMscgen() { 32 32 - var script = document.createElement('script'); 33 33 - script.src = %S; 34 34 - script.async = false; 35 35 - document.head.appendChild(script); 36 36 - } 37 37 - if (document.readyState === 'loading') { 38 38 - document.addEventListener('DOMContentLoaded', loadMscgen); 39 39 - } else { 40 40 - loadMscgen(); 41 41 - } 42 42 - })(); 43 43 - |} mscgen_js_url 44 44 - 45 45 - 46 46 - (** Generate a unique ID for each diagram *) 47 47 - let diagram_counter = ref 0 48 48 - 49 49 - let fresh_id () = 50 50 - incr diagram_counter; 51 51 - Printf.sprintf "msc-diagram-%d" !diagram_counter 52 52 - 53 53 - (** Extract option values *) 54 54 - let get_style tags = 55 55 - Api.get_binding "named-style" tags 56 56 - |> Option.value ~default:"basic" 57 57 - 58 58 - let get_format tags = 59 59 - Api.get_binding "format" tags 60 60 - 61 61 - let get_filename tags = 62 62 - Api.get_binding "filename" tags 63 63 - 64 64 - (** Extract CSS dimensions *) 65 65 - let get_dimensions tags = 66 66 - let width = Api.get_binding "width" tags in 67 67 - let height = Api.get_binding "height" tags in 68 68 - (width, height) 69 69 - 70 70 - (** Build inline style string from dimensions *) 71 71 - let make_style width height = 72 72 - let parts = [] in 73 73 - let parts = match width with 74 74 - | Some w -> Printf.sprintf "width: %s" w :: parts 75 75 - | None -> parts 76 76 - in 77 77 - let parts = match height with 78 78 - | Some h -> Printf.sprintf "height: %s" h :: parts 79 79 - | None -> parts 80 80 - in 81 81 - match parts with 82 82 - | [] -> "" 83 83 - | ps -> String.concat "; " (List.rev ps) 84 84 - 85 85 - (** HTML-escape content for safe embedding *) 86 86 - let html_escape s = 87 87 - let buf = Buffer.create (String.length s) in 88 88 - String.iter (fun c -> 89 89 - match c with 90 90 - | '<' -> Buffer.add_string buf "&lt;" 91 91 - | '>' -> Buffer.add_string buf "&gt;" 92 92 - | '&' -> Buffer.add_string buf "&amp;" 93 93 - | '"' -> Buffer.add_string buf "&quot;" 94 94 - | c -> Buffer.add_char buf c 95 95 - ) s; 96 96 - Buffer.contents buf 97 97 - 98 98 - (** Run mscgen to render to a specific format *) 99 99 - let run_mscgen ~format content = 100 100 - let tmp_in = Filename.temp_file "odoc_msc_" ".msc" in 101 101 - let tmp_out = Filename.temp_file "odoc_msc_" ("." ^ format) in 102 102 - Fun.protect ~finally:(fun () -> 103 103 - (try Sys.remove tmp_in with _ -> ()); 104 104 - (try Sys.remove tmp_out with _ -> ()) 105 105 - ) (fun () -> 106 106 - (* Write MSC content *) 107 107 - let oc = open_out tmp_in in 108 108 - output_string oc content; 109 109 - close_out oc; 110 110 - (* Run mscgen command *) 111 111 - let cmd = Printf.sprintf "mscgen -T %s -i %s -o %s 2>&1" 112 112 - format (Filename.quote tmp_in) (Filename.quote tmp_out) in 113 113 - let ic = Unix.open_process_in cmd in 114 114 - let error_output = Buffer.create 256 in 115 115 - (try 116 116 - while true do 117 117 - Buffer.add_string error_output (input_line ic); 118 118 - Buffer.add_char error_output '\n' 119 119 - done 120 120 - with End_of_file -> ()); 121 121 - let status = Unix.close_process_in ic in 122 122 - match status with 123 123 - | Unix.WEXITED 0 -> 124 124 - (* Read the output file *) 125 125 - let ic = open_in_bin tmp_out in 126 126 - let len = in_channel_length ic in 127 127 - let data = Bytes.create len in 128 128 - really_input ic data 0 len; 129 129 - close_in ic; 130 130 - Ok data 131 131 - | _ -> 132 132 - Error (Buffer.contents error_output) 133 133 - ) 134 134 - 135 135 - module Msc_handler : Api.Code_Block_Extension = struct 136 136 - let prefix = "msc" 137 137 - 138 138 - let to_document meta content = 139 139 - let id = fresh_id () in 140 140 - let style_name = get_style meta.Api.tags in 141 141 - let format = get_format meta.Api.tags in 142 142 - let filename_opt = get_filename meta.Api.tags in 143 143 - let (width, height) = get_dimensions meta.Api.tags in 144 144 - let style = make_style width height in 145 145 - let style_attr = if style = "" then "" else Printf.sprintf " style=\"%s\"" style in 146 146 - 147 147 - match format with 148 148 - | Some "png" | Some "svg" -> 149 149 - (* Server-side rendering with mscgen *) 150 150 - let fmt = match format with Some f -> f | None -> "png" in 151 151 - let base_filename = match filename_opt with 152 152 - | Some f -> f 153 153 - | None -> Printf.sprintf "msc-%s.%s" id fmt 154 154 - in 155 155 - (match run_mscgen ~format:fmt content with 156 156 - | Ok data -> 157 157 - let html = Printf.sprintf 158 158 - {|<div id="%s" class="odoc-msc-diagram"%s><img src="%s" alt="MSC diagram" /></div>|} 159 159 - id style_attr base_filename 160 160 - in 161 161 - let block = Block.[{ 162 162 - attr = ["odoc-msc"]; 163 163 - desc = Raw_markup ("html", html) 164 164 - }] in 165 165 - Some { 166 166 - Api.content = block; 167 167 - overrides = []; 168 168 - resources = []; 169 169 - assets = [{ Api.asset_filename = base_filename; asset_content = data }]; 170 170 - } 171 171 - | Error err -> 172 172 - (* Show error message *) 173 173 - let html = Printf.sprintf 174 174 - "<div id=\"%s\" class=\"odoc-msc-diagram odoc-msc-error\"><pre style=\"color: red;\">Error rendering MSC diagram (is mscgen installed?):\n%s</pre><pre>%s</pre></div>" 175 175 - id err (html_escape content) 176 176 - in 177 177 - let block = Block.[{ 178 178 - attr = ["odoc-msc"; "odoc-msc-error"]; 179 179 - desc = Raw_markup ("html", html) 180 180 - }] in 181 181 - Some { 182 182 - Api.content = block; 183 183 - overrides = []; 184 184 - resources = []; 185 185 - assets = []; 186 186 - }) 187 187 - 188 188 - | Some unknown_format -> 189 189 - let html = Printf.sprintf 190 190 - {|<div class="odoc-msc-error"><pre style="color: red;">Unknown format: %s (supported: png, svg)</pre></div>|} 191 191 - unknown_format 192 192 - in 193 193 - let block = Block.[{ 194 194 - attr = ["odoc-msc-error"]; 195 195 - desc = Raw_markup ("html", html) 196 196 - }] in 197 197 - Some { 198 198 - Api.content = block; 199 199 - overrides = []; 200 200 - resources = []; 201 201 - assets = []; 202 202 - } 203 203 - 204 204 - | None -> 205 205 - (* Default: client-side JavaScript rendering *) 206 206 - let data_style = if style_name = "basic" then "" else Printf.sprintf " data-named-style=\"%s\"" style_name in 207 207 - let html = Printf.sprintf 208 208 - {|<div id="%s" class="odoc-msc-diagram"%s><script type="text/x-mscgen"%s>%s</script><noscript><pre>%s</pre></noscript></div>|} 209 209 - id style_attr data_style content (html_escape content) 210 210 - in 211 211 - let block = Block.[{ 212 212 - attr = ["odoc-msc"]; 213 213 - desc = Raw_markup ("html", html) 214 214 - }] in 215 215 - Some { 216 216 - Api.content = block; 217 217 - overrides = []; 218 218 - resources = [ 219 219 - Api.Js_inline loader_script; 220 220 - ]; 221 221 - assets = []; 222 222 - } 223 223 - end 224 224 - 225 225 - (** CSS for MSC diagrams *) 226 226 - let msc_css = {| 227 227 - .odoc-msc-diagram { 228 228 - margin: 1em 0; 229 229 - overflow: auto; 230 230 - } 231 231 - 232 232 - .odoc-msc-diagram svg, 233 233 - .odoc-msc-diagram img { 234 234 - max-width: 100%; 235 235 - height: auto; 236 236 - } 237 237 - 238 238 - /* Fallback for noscript */ 239 239 - .odoc-msc-diagram noscript pre { 240 240 - background: #f8f8f8; 241 241 - padding: 1em; 242 242 - border-radius: 4px; 243 243 - overflow-x: auto; 244 244 - } 245 245 - 246 246 - .odoc-msc-error pre { 247 247 - color: #c00; 248 248 - } 249 249 - |} 250 250 - 251 251 - (** Extension documentation *) 252 252 - let extension_info : Api.extension_info = { 253 253 - info_kind = `Code_block; 254 254 - info_prefix = "msc"; 255 255 - info_description = "Render Message Sequence Charts. Uses client-side mscgen-inpage.js by default, or server-side mscgen with format=png|svg."; 256 256 - info_options = [ 257 257 - { opt_name = "format"; opt_description = "Output format: png, svg (requires mscgen), or omit for client-side JS"; opt_default = None }; 258 258 - { opt_name = "named-style"; opt_description = "MscGen style (basic, lazy, classic, etc.)"; opt_default = Some "basic" }; 259 259 - { opt_name = "width"; opt_description = "CSS width (e.g., 500px, 100%)"; opt_default = None }; 260 260 - { opt_name = "height"; opt_description = "CSS height"; opt_default = None }; 261 261 - { opt_name = "filename"; opt_description = "Output filename for server-side rendering"; opt_default = Some "auto-generated" }; 262 262 - ]; 263 263 - info_example = Some "{@msc format=png[msc { a,b; a->b; }]}"; 264 264 - } 265 265 - 266 266 - let () = 267 267 - Api.Registry.register_code_block (module Msc_handler); 268 268 - Api.Registry.register_extension_info extension_info; 269 269 - Api.Registry.register_support_file ~prefix:"msc" { 270 270 - filename = "extensions/msc.css"; 271 271 - content = msc_css; 272 272 - }

-29

odoc-dot-extension.opam

reviewed

··· 1 1 - opam-version: "2.0" 2 2 - version: "dev" 3 3 - synopsis: "Graphviz/DOT diagram support for odoc documentation" 4 4 - description: """ 5 5 - Renders {@dot[...]} code blocks as SVG diagrams using Graphviz. 6 6 - Supports width, height, and layout engine options.""" 7 7 - maintainer: ["Jon Ludlam <jon@recoil.org>"] 8 8 - authors: ["Jon Ludlam <jon@recoil.org>"] 9 9 - license: "ISC" 10 10 - homepage: "https://github.com/ocaml/odoc" 11 11 - bug-reports: "https://github.com/ocaml/odoc/issues" 12 12 - dev-repo: "git+https://github.com/ocaml/odoc.git" 13 13 - depends: [ 14 14 - "dune" {>= "3.18"} 15 15 - "ocaml" {>= "4.14"} 16 16 - "odoc" {= version} 17 17 - ] 18 18 - build: [ 19 19 - [ 20 20 - "dune" 21 21 - "build" 22 22 - "-p" 23 23 - name 24 24 - "-j" 25 25 - jobs 26 26 - "@install" 27 27 - ] 28 28 - ] 29 29 - x-maintenance-intent: ["(latest)"]

-29

odoc-mermaid-extension.opam

reviewed

··· 1 1 - opam-version: "2.0" 2 2 - version: "dev" 3 3 - synopsis: "Mermaid diagram support for odoc documentation" 4 4 - description: """ 5 5 - Renders {@mermaid[...]} code blocks as interactive diagrams. 6 6 - Supports flowcharts, sequence diagrams, class diagrams, and more.""" 7 7 - maintainer: ["Jon Ludlam <jon@recoil.org>"] 8 8 - authors: ["Jon Ludlam <jon@recoil.org>"] 9 9 - license: "ISC" 10 10 - homepage: "https://github.com/ocaml/odoc" 11 11 - bug-reports: "https://github.com/ocaml/odoc/issues" 12 12 - dev-repo: "git+https://github.com/ocaml/odoc.git" 13 13 - depends: [ 14 14 - "dune" {>= "3.18"} 15 15 - "ocaml" {>= "4.14"} 16 16 - "odoc" {= version} 17 17 - ] 18 18 - build: [ 19 19 - [ 20 20 - "dune" 21 21 - "build" 22 22 - "-p" 23 23 - name 24 24 - "-j" 25 25 - jobs 26 26 - "@install" 27 27 - ] 28 28 - ] 29 29 - x-maintenance-intent: ["(latest)"]

-29

odoc-msc-extension.opam

reviewed

··· 1 1 - opam-version: "2.0" 2 2 - version: "dev" 3 3 - synopsis: "Message Sequence Chart support for odoc documentation" 4 4 - description: """ 5 5 - Renders {@msc[...]} code blocks as message sequence charts. 6 6 - Uses the MscGen syntax for defining sequence diagrams.""" 7 7 - maintainer: ["Jon Ludlam <jon@recoil.org>"] 8 8 - authors: ["Jon Ludlam <jon@recoil.org>"] 9 9 - license: "ISC" 10 10 - homepage: "https://github.com/ocaml/odoc" 11 11 - bug-reports: "https://github.com/ocaml/odoc/issues" 12 12 - dev-repo: "git+https://github.com/ocaml/odoc.git" 13 13 - depends: [ 14 14 - "dune" {>= "3.18"} 15 15 - "ocaml" {>= "4.14"} 16 16 - "odoc" {= version} 17 17 - ] 18 18 - build: [ 19 19 - [ 20 20 - "dune" 21 21 - "build" 22 22 - "-p" 23 23 - name 24 24 - "-j" 25 25 - jobs 26 26 - "@install" 27 27 - ] 28 28 - ] 29 29 - x-maintenance-intent: ["(latest)"]