I'd like to inquire about the state of rendering math in rust documentation.
I'm still a bit confused after clicking my way through many different GitHub issues, but it seems that there were various requests for this over time and some attempts to make it happen but as far as I can tell none of them have panned out and all issues related to this seem to be closed? I also could not find an RFC on this. Please correct me if I missed something!! I am not sure if I truly looked everywhere (e.g. Zulip?).
From what I can gather the current solution is to inject an html header containing Katex via an environment variable (for building locally via
cargo doc) and a flag in Cargo.toml like so (for crates.io):
rustdoc-args = [
katex-header.html is a file like referenced here. I took that crate as an example in general to make rendering math in docs work because I didn't find this process intuitive at all. Someone has mentioned
katex_doc (repo) but that repo has been archived.
I'm a bit surprised at how hard it is to display math given how praised the state of documentation is in Rust, as in my opinion math is absolutely necessary to document code. Granted, the crate I would like to publish is in the space of crates that absolutely cannot be documented without using math, and I respect that not all crates are like this.
Is this still being worked on / explored?
I should give a quick mention to Mermaid.js here because while rendering math is definitely the priority, visualizing (e.g. architectural) concepts with diagrams is also very nice-to-have, although you could get away with just embedding an image here which seems to be actively worked on (Issue) (RFC)