Update generated API docs

docs/_html/ppx_minidebug/Minidebug_runtime/PrintBox/index.html

@@ -15,4 +15,4 @@
   <span><span class="label">descr</span>:string <span class="arrow">&#45;&gt;</span></span>
   <span><span class="label">pp</span>:<span>(<span><span class="xref-unresolved">Stdlib</span>.Format.formatter <span class="arrow">&#45;&gt;</span></span> <span><span class="type-var">'a</span> <span class="arrow">&#45;&gt;</span></span> unit)</span> <span class="arrow">&#45;&gt;</span></span>
   <span><span class="label">v</span>:<span class="type-var">'a</span> <span class="arrow">&#45;&gt;</span></span>
-  unit</span></code></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-log_value_show"><a href="#val-log_value_show" class="anchor"></a><code><span><span class="keyword">val</span> log_value_show : <span><span class="label">descr</span>:string <span class="arrow">&#45;&gt;</span></span> <span><span class="label">v</span>:string <span class="arrow">&#45;&gt;</span></span> unit</span></code></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-exceeds_max_nesting"><a href="#val-exceeds_max_nesting" class="anchor"></a><code><span><span class="keyword">val</span> exceeds_max_nesting : <span>unit <span class="arrow">&#45;&gt;</span></span> bool</span></code></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-exceeds_max_children"><a href="#val-exceeds_max_children" class="anchor"></a><code><span><span class="keyword">val</span> exceeds_max_children : <span>unit <span class="arrow">&#45;&gt;</span></span> bool</span></code></div></div></details></div><div class="odoc-spec"><div class="spec value anchored" id="val-no_debug_if"><a href="#val-no_debug_if" class="anchor"></a><code><span><span class="keyword">val</span> no_debug_if : <span>bool <span class="arrow">&#45;&gt;</span></span> unit</span></code></div><div class="spec-doc"><p>When passed true within the scope of a log subtree, disables the logging of this subtree and its subtrees. Does not do anything when passed false (<code>no_debug_if false</code> does <em>not</em> re-enable the log).</p></div></div></details></div><div class="odoc-spec"><div class="spec value anchored" id="val-to_html"><a href="#val-to_html" class="anchor"></a><code><span><span class="keyword">val</span> to_html : <span>bool <span class="xref-unresolved">Stdlib</span>.ref</span></span></code></div><div class="spec-doc"><p>While <code>true</code>, logs are generated as html; if <code>false</code>, as monospaced text.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-boxify_sexp_from_size"><a href="#val-boxify_sexp_from_size" class="anchor"></a><code><span><span class="keyword">val</span> boxify_sexp_from_size : <span>int <span class="xref-unresolved">Stdlib</span>.ref</span></span></code></div><div class="spec-doc"><p>If positive, <code>Sexp.t</code>-based logs with this many or more atoms are converted to print-boxes before logging.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-highlight_terms"><a href="#val-highlight_terms" class="anchor"></a><code><span><span class="keyword">val</span> highlight_terms : <span><span><span class="xref-unresolved">Re</span>.re option</span> <span class="xref-unresolved">Stdlib</span>.ref</span></span></code></div><div class="spec-doc"><p>Uses a highlight style for logs on paths ending with a log matching the regular expression.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-exclude_on_path"><a href="#val-exclude_on_path" class="anchor"></a><code><span><span class="keyword">val</span> exclude_on_path : <span><span><span class="xref-unresolved">Re</span>.re option</span> <span class="xref-unresolved">Stdlib</span>.ref</span></span></code></div><div class="spec-doc"><p>Does not propagate the highlight status from child logs through log headers matching the given regular expression.</p></div></div></div></body></html>
+  unit</span></code></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-log_value_show"><a href="#val-log_value_show" class="anchor"></a><code><span><span class="keyword">val</span> log_value_show : <span><span class="label">descr</span>:string <span class="arrow">&#45;&gt;</span></span> <span><span class="label">v</span>:string <span class="arrow">&#45;&gt;</span></span> unit</span></code></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-exceeds_max_nesting"><a href="#val-exceeds_max_nesting" class="anchor"></a><code><span><span class="keyword">val</span> exceeds_max_nesting : <span>unit <span class="arrow">&#45;&gt;</span></span> bool</span></code></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-exceeds_max_children"><a href="#val-exceeds_max_children" class="anchor"></a><code><span><span class="keyword">val</span> exceeds_max_children : <span>unit <span class="arrow">&#45;&gt;</span></span> bool</span></code></div></div></details></div><div class="odoc-spec"><div class="spec value anchored" id="val-no_debug_if"><a href="#val-no_debug_if" class="anchor"></a><code><span><span class="keyword">val</span> no_debug_if : <span>bool <span class="arrow">&#45;&gt;</span></span> unit</span></code></div><div class="spec-doc"><p>When passed true within the scope of a log subtree, disables the logging of this subtree and its subtrees. Does not do anything when passed false (<code>no_debug_if false</code> does <em>not</em> re-enable the log).</p></div></div></details></div><div class="odoc-spec"><div class="spec value anchored" id="val-to_html"><a href="#val-to_html" class="anchor"></a><code><span><span class="keyword">val</span> to_html : <span>bool <span class="xref-unresolved">Stdlib</span>.ref</span></span></code></div><div class="spec-doc"><p>While <code>true</code>, logs are generated as html; if <code>false</code>, as monospaced text.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-boxify_sexp_from_size"><a href="#val-boxify_sexp_from_size" class="anchor"></a><code><span><span class="keyword">val</span> boxify_sexp_from_size : <span>int <span class="xref-unresolved">Stdlib</span>.ref</span></span></code></div><div class="spec-doc"><p>If positive, <code>Sexp.t</code>-based logs with this many or more atoms are converted to print-boxes before logging.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-highlight_terms"><a href="#val-highlight_terms" class="anchor"></a><code><span><span class="keyword">val</span> highlight_terms : <span><span><span class="xref-unresolved">Re</span>.re option</span> <span class="xref-unresolved">Stdlib</span>.ref</span></span></code></div><div class="spec-doc"><p>Uses a highlight style for logs on paths ending with a log matching the regular expression.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-exclude_on_path"><a href="#val-exclude_on_path" class="anchor"></a><code><span><span class="keyword">val</span> exclude_on_path : <span><span><span class="xref-unresolved">Re</span>.re option</span> <span class="xref-unresolved">Stdlib</span>.ref</span></span></code></div><div class="spec-doc"><p>Does not propagate the highlight status from child logs through log headers matching the given regular expression.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-highlighted_roots"><a href="#val-highlighted_roots" class="anchor"></a><code><span><span class="keyword">val</span> highlighted_roots : <span>bool <span class="xref-unresolved">Stdlib</span>.ref</span></span></code></div><div class="spec-doc"><p>If set to true, only ouptputs highlighted toplevel boxes. This makes it simpler to trim excessive logging while still providing all the context. Defaults to <code>false</code>.</p></div></div></div></body></html>

docs/_html/ppx_minidebug/Minidebug_runtime/index.html

@@ -11,6 +11,7 @@
   <span><span class="optlabel">?max_num_children</span>:int <span class="arrow">&#45;&gt;</span></span>
   <span><span class="optlabel">?highlight_terms</span>:<span class="xref-unresolved">Re</span>.t <span class="arrow">&#45;&gt;</span></span>
   <span><span class="optlabel">?exclude_on_path</span>:<span class="xref-unresolved">Re</span>.t <span class="arrow">&#45;&gt;</span></span>
+  <span><span class="optlabel">?highlighted_roots</span>:bool <span class="arrow">&#45;&gt;</span></span>
   <span><span class="optlabel">?for_append</span>:bool <span class="arrow">&#45;&gt;</span></span>
   <span><span class="optlabel">?boxify_sexp_from_size</span>:int <span class="arrow">&#45;&gt;</span></span>
   <span>string <span class="arrow">&#45;&gt;</span></span>
@@ -21,6 +22,7 @@
   <span><span class="optlabel">?max_num_children</span>:int <span class="arrow">&#45;&gt;</span></span>
   <span><span class="optlabel">?highlight_terms</span>:<span class="xref-unresolved">Re</span>.t <span class="arrow">&#45;&gt;</span></span>
   <span><span class="optlabel">?exclude_on_path</span>:<span class="xref-unresolved">Re</span>.t <span class="arrow">&#45;&gt;</span></span>
+  <span><span class="optlabel">?highlighted_roots</span>:bool <span class="arrow">&#45;&gt;</span></span>
   <span>unit <span class="arrow">&#45;&gt;</span></span>
   <span>(<span class="keyword">module</span> <a href="module-type-Debug_runtime_cond/index.html">Debug_runtime_cond</a>)</span></span></code></div><div class="spec-doc"><p>Creates a PrintBox-based debug runtime. By default it will log to <code>stdout</code> and will not be time tagged.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-debug_flushing"><a href="#val-debug_flushing" class="anchor"></a><code><span><span class="keyword">val</span> debug_flushing : 
   <span><span class="optlabel">?debug_ch</span>:<span class="xref-unresolved">Stdlib</span>.out_channel <span class="arrow">&#45;&gt;</span></span>

docs/_html/ppx_minidebug/index.html

@@ -6,7 +6,7 @@
   Minidebug_runtime.PrintBox ((val Minidebug_runtime.debug_ch "debug.html"))
 let () = Debug_runtime.to_html := true
 let () = Debug_runtime.boxify_sexp_from_size := 50</code></pre><p><code>debug_html</code> is a configurable shorthand for the above setup:</p><pre class="language-ocaml"><code>module Debug_runtime = (val Minidebug_runtime.debug_html &quot;debug.html&quot;)</code></pre><p>Similarly, <code>debug</code> and <code>debug_flushing</code> are configurable shorthands that default to logging to <code>stdout</code> (but accept a `~debug_ch` argument).</p><h4 id="debugging-infinite-loops"><a href="#debugging-infinite-loops" class="anchor"></a>Debugging infinite loops</h4><p>Computation can be optionally interruped using the <code>~max_nesting_depth</code> and <code>~max_num_children</code> settings. The first raises a failure when the nesting of logs exceeds the given threshold, the second raises a failure when the number of log entries under a single parent exceeds the threshold. E.g.:</p><pre class="language-ocaml"><code>module Debug_runtime =
-  (val Minidebug_runtime.debug_html ~max_nesting_depth:20 ~max_num_children:50 &quot;debug.html&quot;)</code></pre><p>The cutoff points are indicated in the logs.</p><h4 id="searching-and-navigating-the-logs"><a href="#searching-and-navigating-the-logs" class="anchor"></a>Searching and navigating the logs</h4><p>Currently (since 0.7.0) there is just one support mechanism for taming complex logs: a <code>highlight_terms</code> regular expression in the PrintBox runtime. Paths to logs that match <code>highlight_terms</code> are printed with a frame / border: around the log and around summaries on the path to the log. A corresponding setting `exclude_on_path` will disable highlighting on logs (summaries) this regular expression matches on, regardless of children. Therefore, `exclude_on_path` stops the propagation of highlights upward.</p><h3 id="vs-code-suggestions"><a href="#vs-code-suggestions" class="anchor"></a>VS Code suggestions</h3><h4 id="add-/-remove-type-annotations-and-visit-files-using-vocaml"><a href="#add-/-remove-type-annotations-and-visit-files-using-vocaml" class="anchor"></a>Add / remove type annotations and visit files using <em>VOCaml</em></h4><p><a href="https://marketplace.visualstudio.com/items?itemName=lukstafi.vocaml">VOCaml helpers for coding in OCaml</a> provide commands to add and remove annotations on selected bindings. They can be used to introduce logging, tune it, and cleanup afterward. It also has a command to populate the _Quick Open_ dialog with a file name and location from a line under cursor. It can be used to jump to the source code from a log file.</p><p>Note that you can add and remove type annotations using VSCode OCaml Platform's code actions, and the <em>Find and Transform</em> suggestion below is a more flexible go-to-file solution -- so VOCaml is somewhat redundant. But, it is still valuable: (1) it annotates multiple <code>let</code>-bindings at once in a selection, and (2) it annotates the argument types and the return type of a function (as required by <code>ppx_debug</code>) when invoked on a function definition.</p><h4 id="visualize-the-flame-graph-using-log-inspector"><a href="#visualize-the-flame-graph-using-log-inspector" class="anchor"></a>Visualize the flame graph using <em>Log Inspector</em></h4><p><a href="https://marketplace.visualstudio.com/items?itemName=lukstafi.loginspector-submillisecond">Log Inspector (sub-millisecond)</a>'s main feature is visualizing timestamped logs as flame graphs. To invoke it in VS Code, go to the <code>Minidebug_runtime.Flushing</code>-style logs file, press <em>crtl+shift+P</em>, and execute the command <em>Log Inspector: Draw</em>.</p><p>The sub-millisecond functionality is now upstreamed to <a href="https://marketplace.visualstudio.com/items?itemName=LogInspector.loginspector">Log Inspector</a>.</p><h4 id="go-to-file-location-using-find-and-transform"><a href="#go-to-file-location-using-find-and-transform" class="anchor"></a>Go to file location using <em>Find and Transform</em></h4><p>This will expand your general-purpose VS Code toolbox!</p><p><a href="https://marketplace.visualstudio.com/items?itemName=ArturoDent.find-and-transform">Find and Transform</a> is a powerful VS Code extension. I put the following in my `keybindings.json` file (command: <em>Open Keyboard Shortcuts (JSON)</em>):</p><pre class="language-json"><code>{
+  (val Minidebug_runtime.debug_html ~max_nesting_depth:20 ~max_num_children:50 &quot;debug.html&quot;)</code></pre><p>The cutoff points are indicated in the logs.</p><h4 id="searching-and-navigating-the-logs"><a href="#searching-and-navigating-the-logs" class="anchor"></a>Searching and navigating the logs</h4><p>Currently (since 0.7.0) there is just one support mechanism for taming complex logs: a <code>highlight_terms</code> regular expression in the PrintBox runtime. Paths to logs that match <code>highlight_terms</code> are printed with a frame / border: around the log and around summaries on the path to the log. A corresponding setting `exclude_on_path` will disable highlighting on logs (summaries) this regular expression matches on, regardless of children. Therefore, `exclude_on_path` stops the propagation of highlights upward. There is also an optional flag <code>highlighted_roots</code>, to only output highlighted toplevel boxes. This makes it simpler to trim excessive logging while still providing all the context.</p><h3 id="vs-code-suggestions"><a href="#vs-code-suggestions" class="anchor"></a>VS Code suggestions</h3><h4 id="add-/-remove-type-annotations-and-visit-files-using-vocaml"><a href="#add-/-remove-type-annotations-and-visit-files-using-vocaml" class="anchor"></a>Add / remove type annotations and visit files using <em>VOCaml</em></h4><p><a href="https://marketplace.visualstudio.com/items?itemName=lukstafi.vocaml">VOCaml helpers for coding in OCaml</a> provide commands to add and remove annotations on selected bindings. They can be used to introduce logging, tune it, and cleanup afterward. It also has a command to populate the _Quick Open_ dialog with a file name and location from a line under cursor. It can be used to jump to the source code from a log file.</p><p>Note that you can add and remove type annotations using VSCode OCaml Platform's code actions, and the <em>Find and Transform</em> suggestion below is a more flexible go-to-file solution -- so VOCaml is somewhat redundant. But, it is still valuable: (1) it annotates multiple <code>let</code>-bindings at once in a selection, and (2) it annotates the argument types and the return type of a function (as required by <code>ppx_debug</code>) when invoked on a function definition.</p><h4 id="visualize-the-flame-graph-using-log-inspector"><a href="#visualize-the-flame-graph-using-log-inspector" class="anchor"></a>Visualize the flame graph using <em>Log Inspector</em></h4><p><a href="https://marketplace.visualstudio.com/items?itemName=lukstafi.loginspector-submillisecond">Log Inspector (sub-millisecond)</a>'s main feature is visualizing timestamped logs as flame graphs. To invoke it in VS Code, go to the <code>Minidebug_runtime.Flushing</code>-style logs file, press <em>crtl+shift+P</em>, and execute the command <em>Log Inspector: Draw</em>.</p><p>The sub-millisecond functionality is now upstreamed to <a href="https://marketplace.visualstudio.com/items?itemName=LogInspector.loginspector">Log Inspector</a>.</p><h4 id="go-to-file-location-using-find-and-transform"><a href="#go-to-file-location-using-find-and-transform" class="anchor"></a>Go to file location using <em>Find and Transform</em></h4><p>This will expand your general-purpose VS Code toolbox!</p><p><a href="https://marketplace.visualstudio.com/items?itemName=ArturoDent.find-and-transform">Find and Transform</a> is a powerful VS Code extension. I put the following in my `keybindings.json` file (command: <em>Open Keyboard Shortcuts (JSON)</em>):</p><pre class="language-json"><code>{
   &quot;key&quot;: &quot;alt+q&quot;,
   &quot;command&quot;: &quot;findInCurrentFile&quot;,
   &quot;args&quot;: {