What is offered by this crate

The crate provides include_display_mode_tex! macro that allows to embed tex formulae in the documentation generated by rustdoc via cargo doc --no-deps.

Requirements

Nightly compiler

#![feature(proc_macro_span)] is absolutely necessary to imitate the behavior of include_str.

Running rustup default nightly in the terminal will install the nightly version of the tools (cargo, rustc, and so on). Also, it will switch the corresponding commands to use the nightly version. If you want to go back to the stable version, issue the rustup default stable command. Credit to O'Reilly.

What is LaTeX?

LaTeX is a language for typesetting documents, especially scientific papers, and a document preparation system.

Example of .tex code

% ...
\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}
% ...

Output

tex output

Example on docs.rs

zero_based_index crate

Now and future

In its current implementation include_display_mode_tex! macro merely turns the contents of .tex files into Markdown with raw LaTeX formulae. For the formulae to be displayed as such and not LaTeX syntax, Markdown with raw LaTeX must be rendered with some library, such as KaTeX or MathJax. Such approach burdens the crate with extra complexity of .cargo config and the requirement to build the documentation via cargo doc --no-deps instead of cargo doc but it works.

There is also katex crate that theoretically can allow to render HTML when the documentation is generated. A PR with such functionality will be very welcome (though feature-gated for backward compatibility).

Setting up the crate

The following steps will allow to render .tex included via include_display_mode_tex! with KaTeX renderer:

Create .cargo directory in the crate root (the directory containing Cargo.toml)
In .cargo, add config.toml with the following contents:

[build]

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

Add these two lines to your Cargo.toml

[package.metadata.docs.rs]

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

Add include_display_mode_tex as [dependency], not [dev-dependency]
Create ./src/html directory (where ./src/html is a relative path from the crate root)
In ./src/html add docs-header.html with the following contents:

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.15.1/dist/katex.min.css" integrity="sha384-R4558gYOUz8mP9YWpZJjofhk+zx0AS11p36HnD2ZKj/6JR5z27gSSULCNHIRReVs" crossorigin="anonymous">
<script defer src="https://cdn.jsdelivr.net/npm/katex@0.15.1/dist/katex.min.js" integrity="sha384-z1fJDqw8ZApjGO3/unPWUPsIymfsJmyrDVWC8Tv/a1HeOtGmkwNd/7xUS0Xcnvsx" crossorigin="anonymous"></script>
<script defer src="https://cdn.jsdelivr.net/npm/katex@0.15.1/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>

Code example

use include_display_mode_tex::include_display_mode_tex;

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

Notice that the path is relative not to the crate root but to the call site (just like for core::include_str) and that the documentation must be built with

cargo doc --no-deps

Sources of inspiration

Other include* macros:

Special thanks to victe for providing rust-latex-doc-minimal-example

include_display_mode_tex 0.1.3