KaTeX for documentation

[LukeMathWalker]

A new crate, hmmm, has just been released.
It's a super cool project, dealing with Hidden Markov Model Models, but the relevant piece for ndarray is its documentation: @paulkernfeld managed to get KaTeX to work on doc.rs ❤️

Is this something we might be interested in doing? I'd personally love to have better rendered math than ASCII art 😅

[LukeMathWalker]

The relevant HTML/JS snippet is here and this is how cargo gets told what to do with it (if I got it correctly).

[jturner314]

The KaTeX docs are pretty. :) I found some docs on including KaTeX in Rust docs. There are a few disadvantages, though:

• Building docs locally becomes more difficult:

  cargo doc
  RUSTDOCFLAGS="--html-in-header katex-header.html" cargo doc --no-deps --open

  (There isn't a way to specify the --html-in-header option in Cargo.toml (cargo-doc: enable using --html-in-header and other rustdoc flags rust-lang/cargo#331).)

• The KaTeX rendering wouldn't work for crates that depend on ndarray and build their docs with cargo doc (i.e. users who run cargo doc on their own project for generating docs for their dependencies during development).

• If we get KaTeX working for locally-built docs, rendering the math would require an internet connection (to download KaTeX; unless we copy the KaTeX source into this repo).

I wouldn't mind these issues as long as we can use the existing text-based math as a fallback. Maybe we could keep the text-based math, add KaTeX, and add some JavaScript that hides the the text-based version when KaTeX is working?

[LukeMathWalker]

We could use a JavaScript snippet to have a fallback option, but how do we make sure the snippet itself is included when running cargo doc if we can't set the --html-in-header attribute using Cargo.toml? 🤔

[jturner314]

What I mean is that the existing text-based math would be included in the document and would be visible without any JavaScript snippets (like it is now). The purpose of the JavaScript snippet would be to hide the text-based math when KaTeX is able to render the pretty math (so that the math isn't shown in both text-based and pretty forms). So, the snippet would only need to be included with --html-in-header when KaTeX is included with --html-in-header.