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.
#![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.
LaTeX is a language for typesetting documents, especially scientific papers, and a document preparation system.
```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}
% ... ```
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).
The following steps will allow to render .tex included via include_display_mode_tex!
with KaTeX renderer:
.cargo directory in the crate root (the directory containing Cargo.toml).cargo, add config.toml
with the following contents:
toml
[build]
rustdocflags = [ "--html-in-header", "./src/html/docs-header.html" ]
Cargo.toml
toml
[package.metadata.docs.rs]
rustdoc-args = [ "--html-in-header", "./src/html/docs-header.html" ]
include_display_mode_tex as [dependency], not [dev-dependency]./src/html directory (where ./src/html is a relative path from the crate root)./src/html add docs-header.html with the following contents:
```html
```
```norun use includedisplaymodetex::includedisplaymode_tex;
```
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
text
cargo doc --no-deps
Other include* macros:
* core::include_str
* core::include_bytes
* core::include
* include_dir::include_dir
Special thanks to victe for providing
rust-latex-doc-minimal-example
Licensed under either of Apache License, Version 2.0 or MIT license at your option.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this crate by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.