使用 Latex 在文档中的最小 Rust 项目示例

在 Rust 中记录代码既简单又吸引人，但你不能编写数学表达式。

解决方案是在最终的 HTML 文档页面中包含一个脚本，用于在渲染页面时解析数学表达式。

我们使用 Latex 进行数学语法，使用 Katex 解析最终 HTML 文件中的表达式。该 解析脚本 从 CDN 获取 Katex 并配置文档代码中使用的转义字符。

现在你可以这样做

/// $$E = mc^2 $$
/// $$m = \frac{m_0}{\sqrt{1-\frac{v^2}{c^2}}}$$
fn energy(v: Velocity) -> Energy {...}

结果，请查看此仓库示例的文档页面，位于 docs.rs。

在最终文档中包含解析脚本

rustdoc 有 命令行参数，用于在内容和内容之后包含 HTML，在内容之前。我们使用 --html-in-header，因为我们需要链接到 CDN 来获取 Katex。

将 --html-in-header 传递给 cargo doc 命令有两种选择

1) 使用环境变量 RUSTDOCFLAGS (查看 cargo rustdoc)

Linux

RUSTDOCFLAGS="--html-in-header src/docs-header.html" cargo doc

Windows cmd

set RUSTDOCFLAGS=--html-in-header src\docs-header.html
cargo doc

Windows PowerShell

$env:RUSTDOCFLAGS="--html-in-header .\src\docs-header.html"
cargo doc

2) 在 .cargo\config.toml 中设置 build.rustdocflags 配置值 (在此仓库中已配置)

[build]
rustdocflags = [ "--html-in-header", "./src/docs-header.html" ]

发布 crate 并在 docs.rs 中显示文档

该 crate 必须是 lib。如果是只有 bin，docs.rs 不会构建文档。

我们需要在货物清单中添加头文件位置

[package.metadata.docs.rs]
rustdoc-args = [ "--html-in-header", "./src/docs-header.html" ]

在您的托管平台上发布文档

如果您的crate是bin或者您不想在crates.io上发布crate，您总是可以在方便的时候发布target/doc目录。

在此仓库中，我们在docs目录中使用GitHub Pages。在这种情况下，只需使用

rm -rf docs/ && cargo clean --doc && cargo doc && cp -r target/doc/ docs/

如果您将crate发布到crates.io，请将cargo清单中的documentation条目设置为最终URL目标。在此crate中，此条目应如下所示

# Cargo.toml
[package]
...
documentation = "https://victe.github.io/rust-latex-doc-minimal-example/rust_latex_doc_minimal_example/"
...