The first command to know the version of odoc you are using, the second one is the command (usually called by dune) to generate the support files (in this case in the __test directory), which should normally include katex.min.js.
You can remove the __test directory after that!
Could you also confirm that the file that should render the math includes the (missing apparently) katex lib? For instance, for me:
Sorry for the delay. I have odoc version 2.2.0 and for your test, please find the results below. I must say that I run all of this on a windows box (Diskml distrib) which has had some tricks with odoc…:
PS H:\OCaml\GenArrayIter> tree /F __TEST
Structure du dossier pour le volume Corsair 2
Le numéro de série du volume est 000000FF 0634:1600
H:\OCAML\GENARRAYITER\__TEST
│ highlight.pack.js
│ katex.min.css
│ katex.min.js
│ odoc.css
│
└───fonts
KaTeX_AMS-Regular.woff2
KaTeX_Caligraphic-Regular.woff2
KaTeX_Fraktur-Bold.woff2
KaTeX_Fraktur-Regular.woff2
KaTeX_Main-Bold.woff2
KaTeX_Main-BoldItalic.woff2
KaTeX_Main-Italic.woff2
KaTeX_Main-Regular.woff2
KaTeX_Math-BoldItalic.woff2
KaTeX_Math-Italic.woff2
KaTeX_SansSerif-Bold.woff2
KaTeX_SansSerif-Italic.woff2
KaTeX_SansSerif-Regular.woff2
KaTeX_Script-Regular.woff2
KaTeX_Size1-Regular.woff2
KaTeX_Size2-Regular.woff2
KaTeX_Size3-Regular.woff2
KaTeX_Size4-Regular.woff2
KaTeX_Typewriter-Regular.woff2
PS H:\OCaml\GenArrayIter> odoc --version
2.2.0
As for the file presumably missing katex lib, here is the content of the HTML header supposed to render the formulas :
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>Iter (GenArrayIter.GenArrayIter.Iter)</title>
<link rel="stylesheet" href="../../../odoc.css" />
<meta charset="utf-8" />
<meta name="generator" content="odoc 2.2.0" />
<meta name="viewport" content="width=device-width,initial-scale=1.0" />
<script src="../../../highlight.pack.js"></script>
<script>hljs.initHighlightingOnLoad();</script>
<link rel="stylesheet" href="../../../katex.min.css" />
<script src="../../../katex.min.js"></script>
<script>
//<![CDATA[
document.addEventListener("DOMContentLoaded", function () {
var elements = Array.from(document.getElementsByClassName("odoc-katex-math"));
for (var i = 0; i < elements.length; i++) {
var el = elements[i];
var content = el.textContent;
var new_el = document.createElement("span");
new_el.setAttribute("class", "odoc-katex-math-rendered");
var display = el.classList.contains("display");
katex.render(content, new_el, { throwOnError: false, displayMode: display });
el.replaceWith(new_el);
}
});
//]]>
</script>
</head>
<body class="odoc">
<nav class="odoc-nav"><a href="../index.html">Up</a> – <a href="../../index.html">GenArrayIter</a> » <a
href="../index.html">GenArrayIter</a> » Iter</nav>
<header class="odoc-preamble">
<h1>Module <code><span>GenArrayIter.Iter</span></code></h1>
</header>
<div class="odoc-content">
<div class="odoc-spec">
<div class="spec value anchored" id="val-incr"><a href="#val-incr"
class="anchor"></a><code><span><span class="keyword">val</span> incr : <span><span>int array</span> <span class="arrow">-></span></span> <span><span>int array</span> <span class="arrow">-></span></span> bool</span></code>
</div>
<div class="spec-doc">
<p>Given an index <code class="odoc-katex-math">i(i_0,i_1, ..., i_{n-1})</code> of dimension dims(d_0, d_1, ...,
d_<code>n-1</code>) such that ∀ k in [0;n-1] 0 <= i_k < n_k, the function increment the index
<code>i</code> according to the following recursive algorithm:</p>
// cut
That is very strange: the odoc support-files command does create the katex.min.js and katex.min.css files, but it seems they are not present when the command is called by dune…
Since this is a Diskuv distrib, maybe this is due to some trick you mentioned? Any insight @jbeckford?
Also, which version of dune do you have? It seems, from what I understand from this PR, that dune below 3.7 won’t support math?
A workaround is to copy katex.min.js and katex.min.css “by hand” alongside the odoc.css file (eg by running the odoc support-files -o _build/default/_doc/_html command yourself).
It is only a partial workaround. It did work, but each time I change the source file, the documentation is not/wrongly updated. So the issue is more profond than just a file which is not copied at the right place in my opinion.
Assuming you aren’t an advanced user with a findlib installation, you have always needed opam to run dune. On Unix that has been a magic eval $(opam env) invocation or some .profile modifications. There are magic invocations for Windows as well, but in your case I think you were using a DkML version 1.x from 2 years ago that unsafely hid some of the magic. Unsafe because:
the early integration failed for users in very non-transparent ways like all magic invocations are prone to do
the upcoming opam 2.2 does not (and should not) have that magic, and it is important that there is a sane migration path from DkML to regular opam in the near future
The most beginner-proof / clear / copy-and-pastable / cross-platform / future-compatible way is opam exec -- dune build.
(And I think you’ll be able to drop the opam eval or opam exec when the Dune/opam integration is finished. But someone from dune can confirm that.)