How to write math formulas for Rust documentation?

I'd like to write a math formula in Rust documentation for my crate. Looks like there is basic support of LaTeX as at least power works:

/// $ 2^8 $

Is rendered like:

I'd like to use a fraction in my formula, but unfortunately, this does not work:

/// $ \frac{x}y $

Solution 1:

Similar to Steve's answer, using katex you could follow the approaches from:

• https://docs.rs/rustdoc-katex-demo/0.1.5/rustdoc_katex_demo/, see also the resources section. Kernfeld.
• https://docs.rs/katex-doc/0.1.0/katex_doc/, Durham.

You need to put an html file in your crate in some place with the code to include with the --html-in-header option. Then execute:

Linux:

RUSTDOCFLAGS="--html-in-header path-to-your-header-file.html" cargo doc --no-deps

Windows cmd:

set RUSTDOCFLAGS=--html-in-header path-to-your-header-file.html
cargo doc --no-deps --open

Windows PowerShell:

$env:RUSTDOCFLAGS="--html-in-header .\path-to-your-header-file.html"
cargo doc --no-deps --open

--no-deps is not strictly necessary, but convenient if you do not want to add the header to the doc of another external crates.

For use in http://docs.rs you must place this on Cargo.toml:

[package.metadata.docs.rs]
rustdoc-args = [ "--html-in-header", "path-to-your-header-file.html" ]

The content of the header html file could be (this is the solution of Kernfeld):

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/dist/katex.min.css" integrity="sha384-9eLZqc9ds8eNjO3TmqPeYcDj8n+Qfa4nuSiGYa6DjLNcv9BtN69ZIulL9+8CqC9Y" crossorigin="anonymous">
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/katex.min.js"                  integrity="sha384-K3vbOmF2BtaVai+Qk37uypf7VrgBubhQreNQe9aGsz9lB63dIFiQVlJbr92dw2Lx" crossorigin="anonymous"></script>
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/contrib/auto-render.min.js"    integrity="sha384-kmZOZB5ObwgQnS/DuDg6TScgOiWWBiVt0plIRkZCmE6rDZGrEOQeHM5PcHi+nyqe" crossorigin="anonymous"></script>
<script>
    document.addEventListener("DOMContentLoaded", function() {
        renderMathInElement(document.body, {
            delimiters: [
                {left: "$$", right: "$$", display: true},
                {left: "\\(", right: "\\)", display: false},
                {left: "$", right: "$", display: false},
                {left: "\\[", right: "\\]", display: true}
            ]
        });
    });
</script>

See pwnies for another example (no LaTeX) of extending the possibilities of doc html pages.

UPDATE:

I made a minimal example repo showing all the above. The crate with associated documentation using LaTeX.

Solution 2:

Looks like there is basic support of LaTeX

Not quite. There is support for Markdown, not LaTeX. Stack Overflow also supports Markdown, but a different flavor. For example: a^b => a^b, but a<sup>b</sup> => a^b. Markdown doesn't have support for arbitrary LaTeX. Indeed, your example:

/// Hi
///
/// $ 2^8 $
pub fn what() {

}

Generates something that still contains the $:

The next best thing might be to generate pre-rendered images and then include them in your documentation instead, but an open issue seems to indicate that this isn't currently possible unless you are hosting the images somewhere else.

There was even an issue to support MathJax in rustdoc, but that was closed.

Solution 3:

You can make it work with MathJax and rustdoc's --html-in-header to pass in a link to the script tag it needs. This is very hacky, and won't work on docs.rs, but it can work if you host your own docs.