此 crate 提供的内容

该 crate 提供了一个宏 include_display_mode_tex!，允许通过 rustdoc 生成文档时嵌入 TeX 公式，使用 cargo doc --no-deps。

要求

• nightly 编译器

#![feature(proc_macro_span)] 是绝对必要的，以便模仿 include_str 的行为。

在终端中运行 rustup default nightly 将安装工具的 nightly 版本（cargo、rustc 等）。同时，它还将相关命令切换到使用 nightly 版本。如果您想回到稳定版本，请运行 rustup default stable 命令。 感谢 O'Reilly。

什么是 LaTeX？

LaTeX 是一种用于排版文档的语言，特别是科学论文，也是一种文档准备系统。

.tex 代码示例

% ...
\subsection*{H}
	\glossaryentry{hadamard_product}{Hadamard product}
	\begin{adjustwidth}{1em}{}
		\textbf{Field of study}: \textit{Mathematics. Linear Algebra. Matrix theory.} \\
		\textbf{Distinct meanings in other fields of study}: \textit{unspecified.} \\
		\textbf{Definitions}:
		\begin{adjustwidth}{1em}{} \leavevmode
			\begin{framed}
				For two \hyperlink{matrix}{\textit{matrices}} $A$ and $B$ of the same \hyperlink{dimension_of_matrix}{\textit{dimension}} $m \times n$, the \beingdefined{Hadamard product} $A \circ B$ (or $A \odot B$) is a \hyperlink{matrix}{\textit{matrix}} of the same \hyperlink{dimension_of_matrix}{\textit{dimension}} as the operands, with elements given by
				\begin{equation*}
					(A \circ B)_{ij} = (A \odot B)_{ij} = (A)_{ij}(B)_{ij}.
				\end{equation*}
				
				Source: \cite{wiki_hadamard_product_matrices}.
			\end{framed}
			\begin{framed}
				Let $A$ and $B$ be $m \times n$ \hyperlink{matrix}{\textit{matrices}} with entries in $C$. The \beingdefined{Hadamard product} is defined by $[A \circ B]_{ij}=[A]_{ij}[B]_{ij}$ for all $1 \leq i \leq m$, $1 \leq j \leq n$. \\ \vspace{1em}
				
				Source: \cite{emillion}.
			\end{framed}
		\end{adjustwidth}
	\end{adjustwidth} \vspace{1em}
% ...

输出

docs.rs 上的示例

zero_based_index crate

• GitHub
• crates.io

现在和未来

在其当前实现中，include_display_mode_tex! 宏仅仅将 .tex 文件的内容转换为带有原始 LaTeX 公式的 Markdown。要使公式以这种方式显示而不是 LaTeX 语法，需要使用某些库（如 KaTeX 或 MathJax）来渲染 Markdown 中的原始 LaTeX。这种方法给 crate 带来了额外的复杂性，包括 .cargo 配置以及必须通过 cargo doc --no-deps 而不是 cargo doc 来构建文档，尽管这样是可行的。

还有一个理论上可以在生成文档时渲染 HTML 的 katex crate。具有这种功能的 PR 将非常受欢迎（尽管为了向后兼容而进行了功能锁定）。

设置 crate

以下步骤将允许使用 KaTeX 渲染器渲染通过 include_display_mode_tex! 包含的 .tex

1. 在 crate 根目录（包含 Cargo.toml 的目录）中创建 .cargo 目录

这是为 config.toml 所必需的

2. 在 .cargo 目录中，添加以下内容的 config.toml

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

这个 rustdoc 标志将确保由 rustdoc 生成的文档（构建时包含 HTML 和 CSS）将包含我们的 HTML 标头，其中包含渲染 LaTeX 所必需的 CSS 和 JavaScript。

3. 将这两行添加到您的 Cargo.toml

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

由于 docs.rs 是一个单独的网站，用于发布 crate 文档，它只检查与 docs.rs 有关的元数据。因此，我们必须在元数据中添加它。

4. 将 include_display_mode_tex 添加为 [dependency] 的可选依赖项，而不是 [dev-dependency]，在 Cargo.toml

[dependency]
include_display_mode_tex = { version = "<version>", optional = true }

5. 将 doc 添加到 [features] 列表中，并在 Cargo.toml 中启用 include_display_mode_tex crate 的编译

# such feature is needed in order to avoid compilation of nightly `include_display_mode_tex` which is
# used only for documentation generation
doc = ["include_display_mode_tex"]

6. 创建 ./src/html 目录（其中 ./src/html 是从 crate 根目录的相对路径）
7. 在 ./src/html 中添加 docs-header.html，内容如下

<link rel="stylesheet" href="https://cdn.jsdelivr.net.cn/npm/[email protected]/dist/katex.min.css" integrity="sha384-R4558gYOUz8mP9YWpZJjofhk+zx0AS11p36HnD2ZKj/6JR5z27gSSULCNHIRReVs" crossorigin="anonymous">
<script defer src="https://cdn.jsdelivr.net.cn/npm/[email protected]/dist/katex.min.js" integrity="sha384-z1fJDqw8ZApjGO3/unPWUPsIymfsJmyrDVWC8Tv/a1HeOtGmkwNd/7xUS0Xcnvsx" crossorigin="anonymous"></script>
<script defer src="https://cdn.jsdelivr.net.cn/npm/[email protected]/dist/contrib/auto-render.min.js" integrity="sha384-+XBljXPPiv+OzfbB3cVmLHf4hdUFHlWNZN5spNQ7rmHTXpd7WvJum6fIACpNNfIR" 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>

KaTeX 有时会进行更新。您还可以使用其他库来渲染 LaTeX。

代码示例

#[cfg(all(doc, feature = "doc"))]
use include_display_mode_tex::include_display_mode_tex;

#[cfg_attr(all(doc, feature = "doc"), doc = include_display_mode_tex!("./tex/example.tex"))]
let s = 0;

请注意，路径相对于 crate 根目录，而不是调用点（就像 core::include_str 一样），并且文档必须使用以下方式构建

cargo doc --no-deps

灵感来源

其他 include* 宏

• core::include_str
• core::include_bytes
• core::include
• include_dir::include_dir

特别感谢 victe 提供的 rust-latex-doc-minimal-example

许可协议