如何为Rust文档编写数学公式？

Question

我想在Rust文档中为我的箱子写一个数学公式。看起来至少有power可以提供LaTeX的基本支持：

/// $ 2^8 $

呈现为：

我想在公式中使用小数，但不幸的是，这不起作用：

/// $ \frac{x}y $

Answer 1

类似于Steve's answer，使用katex，您可以遵循以下方法：

• https://docs.rs/rustdoc-katex-demo/0.1.5/rustdoc_katex_demo/，另请参阅资源部分。 Kernfeld。
• [https://docs.rs/katex-doc/0.1.0/katex_doc/，Durham。

您需要将html文件放在板条箱中的某个位置，其代码应包含在--html-in-header选项中。然后执行：

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并非绝对必要，但是如果您不想将标头添加到另一个外部包装箱的文档中，则非常方便。

要在http://docs.rs中使用，必须将其放在Cargo.toml：

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

标题HTML文件的内容可能是（这是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是扩展doc html页面可能性的另一个示例（没有LaTeX）。

UPDATE：

我制作了minimal example repo，显示了以上所有内容。 crate与使用documentation关联的LaTeX。

Answer 2

好像有LaTeX的基本支持

不完全是。支持Markdown，而不是LaTeX。 Stack Overflow还支持Markdown，但风格不同。例如：a^b => a ^ b，但a<sup>b</sup> => a ^b。 Markdown不支持任意LaTeX。确实，您的示例：

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

}

生成仍包含$的内容：

第二个最好的办法可能是生成预渲染的图像，然后将其包含在文档中，但是an open issue似乎表明，除非您将图像托管在其他位置，否则当前无法实现。

甚至有an issue to support MathJax in rustdoc，但已关闭。

Answer 3

您可以使其与MathJax和rustdoc的--html-in-header一起使用，以传递指向所需脚本标签的链接。这非常hacky，无法在docs.rs上使用，但如果您托管自己的文档，则可以使用。